Analyze patient cohorts

POST/tools/cohort

Uses LLM to extract search concepts from natural language and builds patient cohorts with inclusion/exclusion criteria

RequiresBearerauthentication

Header parameters

X-Phenoml-On-Behalf-Ofstringoptional

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

X-Phenoml-Fhir-Providerstringoptional

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

Body parameters

textstringrequired

Natural language text describing the patient cohort criteria

providerstring (uuid)required

FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)

Returns

Successfully analyzed cohort and retrieved patient list

Response fields

successbooleanoptional

Whether the cohort analysis was successful

messagestringoptional

Status message with details about the analysis

patientIdsstring[]optional

Array of patient IDs that match the cohort criteria

patientCountintegeroptional

Total number of patients in the cohort

queriesobject[]optional

Individual search concepts that were identified and executed

resource_typestringoptional

The FHIR resource type identified for this concept

search_paramsstringoptional

FHIR search parameters for this concept

conceptstringoptional

Description of what this search represents

excludebooleanoptional

Whether this is an exclusion criteria

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/tools/cohort" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "female patients over 20 with diabetes but not hypertension",
  "provider": "550e8400-e29b-41d4-a716-446655440000"
}'

200 OKExample Response

{
  "success": true,
  "message": "Cohort analysis completed successfully. Found 33 patients from 2 search concepts.",
  "patientIds": [
    "patient-123",
    "patient-456",
    "patient-789"
  ],
  "patientCount": 33,
  "queries": [
    {
      "resource_type": "Patient",
      "search_params": "gender=female&birthdate=le2004-01-01",
      "concept": "female patients over 20",
      "exclude": false
    },
    {
      "resource_type": "Condition",
      "search_params": "code=44054006",
      "concept": "diabetes",
      "exclude": false
    },
    {
      "resource_type": "Condition",
      "search_params": "code=38341003",
      "concept": "hypertension",
      "exclude": true
    }
  ]
}