API Reference
Authentication
All API requests require authentication using an API key passed in the X-API-Key header.
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: conditions, procedures, findings, allergies, and medications |
/tasks/fhir/{task_id} |
GET | Retrieve results as FHIR Bundle (R4B standard) |
/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.coforix.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
Get Task Results (JSON)
GET /tasks/{task_id}
Retrieve the extraction results for a completed task.
Example Request
curl "https://cdt-beta.coforix.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"
},
{
"id": "f1a2b3c4-d5e6-7890-abcd-333333333333",
"snomed_ct_code": "91936005",
"snomed_ct_term": "Allergy to penicillin (finding)",
"concept_type": "allergy",
"status": "confirmed",
"date": null,
"end_date": null,
"source": "penicillin allergy",
"start": 118,
"end": 136,
"shortened_id": "f1a2b3c4"
}
],
"medications": [
{
"name": "Atorvastatin",
"source": "Atorvastatin 20 mg tablet once daily",
"atc_code": "C10AA05",
"atc_term": "Atorvastatin",
"substances": [],
"strength": "20 mg",
"form": "tablet",
"route": "oral",
"status": "active",
"authored_on": null,
"relative_authored_on": null,
"schedule": {
"frequency": 1,
"period": 1,
"period_unit": "d",
"intakes": [
{
"time": null,
"when": null,
"dose": "1 tablet"
}
],
"as_needed": false,
"as_needed_reason": null,
"daily_amount": null,
"max_dose": null,
"bounds_start": null,
"bounds_end": null,
"bounds_duration": null,
"bounds_duration_unit": null
},
"start": 205,
"end": 241
}
],
"specialty": "Cardiology",
"snomed_ct_version": "2026-01-01",
"language": "en"
},
"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 or allergy |
status |
What the note asserts about the concept. The vocabulary depends on concept_type: a disorder, finding or allergy carries how certain the assertion is — confirmed, provisional, differential or refuted — while a procedure carries what became of the act — completed, preparation, in-progress or not-done |
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 |
Medication Fields
Medications are returned in json_data.medications, in the order in which they appear in the note.
| Field | Description |
|---|---|
name |
The drug name as written in the note, brand name included |
source |
The full mention, from the name up to and including strength and form |
atc_code / atc_term |
WHO ATC code and its display. null when the product could not be coded |
substances |
Reserved for the active substances of a combination product, SNOMED CT coded with the amount of each. Not populated in this release: always returned as an empty list, so do not build on its contents |
strength |
The strength exactly as the note states it |
form |
Pharmaceutical form: tablet, capsule, solution, injection, patch, inhaler, and others |
route |
Route of administration: oral, inhalation, transdermal, intravenous, and others |
status |
active, stopped, on-hold, completed or planned |
authored_on |
Date the medication list was drawn up, when the note states one |
schedule |
Dosing, see below |
start / end |
Character offsets in the original note |
Schedule Fields
| Field | Description |
|---|---|
frequency / period / period_unit |
How often the medication is taken, e.g. 2 times per 1 d for "twice daily" |
intakes |
One entry per moment the medication is taken, with its dose, clock time and when (an event such as with meals) |
as_needed / as_needed_reason |
Whether it is taken only when needed, and what for |
daily_amount / max_dose |
Total amount per day, and the maximum the note allows |
bounds_start / bounds_end |
The dates the prescription runs between, when stated |
bounds_duration / bounds_duration_unit |
How long it is prescribed for, when the note gives a length rather than dates |
Uncoded Medications
A medication the ATC classification does not reach is still returned, with atc_code set to null.
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.coforix.ai/tasks/fhir/a1b2c3d4-e5f6-7890-abcd-ef1234567890?fhir_patient_id=patient-123" \
-H "X-API-Key: YOUR_API_KEY"
The bundle carries one resource per extracted concept, chosen by its concept_type:
concept_type |
FHIR resource |
|---|---|
disorder |
Condition |
procedure |
Procedure |
finding |
Observation |
allergy |
AllergyIntolerance |
Each medication is added as the pair FHIR describes a prescription with: a Medication naming the product, coded in ATC, and a MedicationRequest saying how the patient takes it, with the dosing as dosageInstruction.
Every resource carries the extensions tying it back to the text it was read from — text-source, text-index-start and text-index-end — which for a medication sit on the MedicationRequest.
For a description of the FHIR response, please refer to the FHIR Implementation Guide.
Usage Statistics
GET /usage
Retrieve usage statistics for your API key.
Example Request
Example Response
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
Interactive Documentation
Explore the full API with interactive documentation: