Clinical Decision Support

POST /api/v1/ddxThis endpoint generates a list of differential diagnoses based on the provided summary from a consultation. The summary is the only required field. The number of diagnoses returned can be customized, defaulting to 3 if not specified. Additional patient information can also be supplied if not covered in the summary . Each diagnosis in the response includes an explanation detailing the rationale and a recommendation providing guidance on next steps.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Codestring

Clinic code or identifier of the clinic making the API request.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

REQUIREDX-Scrubs-<any-other-header>any

Other required headers depending on your organisation's provider ID.

BODY PARAMETERS

REQUIREDsummarystring

A consultation summary. It does not need to follow the format of summaries from the summary endpoint but should resemble a SOAP note.

OPTIONALadditionalPatientInfostring

Allows additional patient information to be supplied if not covered in the SOAP note.

OPTIONALnumDdxnumber

Specifies how many differentials should be provided. Defaults to 3.

Error Codes5 cases

Endpoint validation

400

Summary is missing or invalid.

summary is required in the JSON body.

Common HCI and authentication errors

400	Provider or HCI configuration is invalid.	Missing or unknown provider ID, no consultation method/auth flow configured for the provider, missing or malformed clinic code, invalid CA origin, or the provider clinic limit is reached.
401	Authentication failed.	API key credentials are missing or invalid, a root clinic/key cannot be found, or no API key is linked to the authenticated clinic.
429	Usage limit reached.	Free-tier usage is exhausted, or a non-root paid API key has expired.

Common runtime errors

500

Unexpected server or upstream failure.

Unhandled JSON/form parsing errors, AI provider failures, transcription provider failures, database errors, or unexpected response parsing failures.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location 'https://usescrubs.com/api/v1/ddx' \
2--header 'X-Scrubs-Clinic-Code: 00A123' \
3--header 'X-Scrubs-Clinic-Provider: SAMPLE_EHR_1' \
4--header 'Content-Type: application/json' \
5--data '{
6    "summary": "Patient reports having a headache for the past week ...",
7    "additionalPatientInfo": "Patient previously diagnosed with Anxiety Disorder",
8    "numDdx": 2
9}'

Sample Response

JSON

1{
2    "diagnosis": [
3        {
4            "diagnosis": "Migraine Headaches",
5            "explanation": "The pattern of headache, particularly the nausea and ...",
6            "recommendation": "Consider triptans for acute management and ..."
7        },
8        {
9            "diagnosis": "Cervicogenic Headache",
10            "explanation": "The symptomatology described could suggest ...",
11            "recommendation": "Evaluate for any cervical spine issues ..."
12        }
13    ]
14}