Skip to content

API Reference

Authentication

All API requests require authentication using an API key passed in the X-API-Key header.

curl -X GET "https://cdt-beta.healthsage.ai/auth/usage" \
  -H "X-API-Key: YOUR_API_KEY"

API Key Security

Your API key is shown only once during signup. Store it securely—we cannot recover it for you.

To receive an API key, request access to the beta program.

Endpoints

Endpoint Method Description
/generate POST Submit a clinical note for processing
/tasks/{task_id} GET Retrieve structured JSON extraction results
/tasks/fhir/{task_id} GET Retrieve results as FHIR Bundle (R4B standard)
/auth/usage GET Get usage statistics for your API key

Submit Clinical Note

POST /generate

Submit a clinical note for processing. Returns a task ID for retrieving results.

Request Body

Field Type Required Description
note string Yes The clinical note text to analyze (max 1500 characters)
specialty string Yes Medical specialty (e.g., "Cardiology", "Oncology"). Use "General Medicine" if no specific specialty
letter_date date No Date of the clinical letter. Defaults to today's date
patient_dob date No Patient's date of birth

Character Limit

The note field has a limit of 1500 characters. For longer clinical documents, split the text into paragraphs and submit each as a separate request.

Example Request

curl -X POST "https://cdt-beta.healthsage.ai/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "67-year-old male with history of paroxysmal atrial fibrillation diagnosed in 2021, hypertension, and hyperlipidemia. Patient underwent pulmonary vein isolation via catheter ablation in September 2023.",
    "specialty": "Cardiology",
    "letter_date": "2025-03-15"
  }'

Example Response

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING"
}

Get Task Results (JSON)

GET /tasks/{task_id}

Retrieve the extraction results for a completed task.

Example Request

curl "https://cdt-beta.healthsage.ai/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "SUCCESS",
  "letter_date": "2025-03-15",
  "patient_dob": null,
  "json_data": {
    "extractions": [
      {
        "id": "f1a2b3c4-d5e6-7890-abcd-111111111111",
        "snomed_ct_code": "282825002",
        "snomed_ct_term": "Paroxysmal atrial fibrillation (disorder)",
        "concept_type": "disorder",
        "status": "confirmed",
        "date": "2021",
        "end_date": null,
        "relative_date": "(Y-4)",
        "relative_end_date": null,
        "source": "paroxysmal atrial fibrillation diagnosed in 2021",
        "start": 42,
        "end": 89,
        "shortened_id": "f1a2b3c4"
      },
      {
        "id": "f1a2b3c4-d5e6-7890-abcd-222222222222",
        "snomed_ct_code": "38341003",
        "snomed_ct_term": "Hypertensive disorder (disorder)",
        "concept_type": "disorder",
        "status": "confirmed",
        "date": null,
        "end_date": null,
        "source": "hypertension",
        "start": 91,
        "end": 103,
        "shortened_id": "f1a2b3c4"
      }
    ],
    "specialty": "Cardiology",
    "snomed_ct_version": "2026-01-01"
  },
  "usage": {
    "input_tokens": 245,
    "output_tokens": 512,
    "total_tokens": 757
  }
}

Extraction Fields

Field Description
snomed_ct_code SNOMED CT concept ID
snomed_ct_term Human-readable SNOMED CT term
concept_type Type: disorder, procedure, finding, etc.
status Confirmation status: confirmed, provisional, differential
date Date associated with the concept (if available)
end_date End date for resolved conditions (if available)
source Original text from which the concept was extracted
start / end Character offsets in the original note

Get Task Results (FHIR)

GET /tasks/fhir/{task_id}

Retrieve the extraction results as a FHIR R4B Bundle.

Query Parameters

Parameter Type Required Description
fhir_patient_id string No FHIR Patient ID to use in resource references. Defaults to <subject_id>

Example Request

curl "https://cdt-beta.healthsage.ai/tasks/fhir/a1b2c3d4-e5f6-7890-abcd-ef1234567890?fhir_patient_id=patient-123" \
  -H "X-API-Key: YOUR_API_KEY"

Usage Statistics

GET /auth/usage

Retrieve usage statistics for your API key.

Example Request

curl "https://cdt-beta.healthsage.ai/auth/usage" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "total_requests": 42,
  "tokens_used": 15230,
  "token_limit": 10000,
  "remaining_tokens": -5230
}

Usage Fields

Field Description
total_requests Total number of API requests made
tokens_used Total output tokens consumed
token_limit Maximum tokens allowed for your API key
remaining_tokens Tokens remaining before limit is reached

Billing

Usage is calculated based on output tokens only.

Error Responses

HTTP Status Codes

Code Description
200 Success
201 Created (signup)
202 Accepted (task submitted)
400 Bad Request - Invalid input
401 Unauthorized - Invalid or missing API key
403 Forbidden - API key inactive
404 Not Found - Task or resource not found
429 Too Many Requests - Token limit exceeded

Error Response Format

{
  "detail": "Token limit exceeded. You have used 10500 tokens out of your 10000 token limit."
}

Interactive Documentation

Explore the full API with interactive documentation:

Open Swagger UI