👾API Reference Docs
Step 1: Get Token
Obtaining a token is the first step when using the API. An active token is required to search and retrieve patient documents from health information exchanges, summarize clinical documents, and push treatment records back into the system. Once you have an active token, it can be reused across all API operations: there’s no need to request a new token for each task.
Description
Retrieves an authentication token
Method
POST
Route
https://api.abstractive.ai/get-token
Success Status Code
200
Limitations
Access token valid for 60 minutes
Avg. Response Time (Success)
~1 second
Authenticates user credentials and returns an access token
Input object to obtain token
User's API email
user@example.comUser's API username. Optional, defaults to user_api_email
user@example.comUser's API password
password123Success
Success token response
Status of the request
successPossible values: HTTP status code
200Possible values: OAuth token for user
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Missing required fields
Unauthorized
Internal server error
POST /get-token HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 105
{
"user_api_email": "user@example.com",
"username_api": "user@example.com",
"user_api_password": "password123"
}{
"status": "success",
"status_code": 200,
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Important Notes
Step 2. Search for a Patient (Optional)
With minimally required patient demographic information - first name, last name, date of birth, and gender - you can initiate a powerful query that retrieves a patient’s lifetime of clinical documentation. We search across 70,000+ healthcare organizations connected via the Carequality® health information exchange, returning a wide range of document types including CDA, FHIR, PDF, TIFF, JPEG, and JSON formats. These retrieved documents form the foundation for generating a complete and clinically accurate medical record summary and delivered directly to you through our API.
Search Patient
Description
Provide a set of patient metadata to kick off an asynchronous Health Information Exchange (HIE) search.
Method
POST
Route
https://api.abstractive.ai/search-patient
Success Status Code
202
Limitations
We will take up to 5 patients per request.
Avg. Response Time (Success)
3 - 5 seconds (time to 202 response)
Searches for patients across multiple EHR systems based on provided metadata
Patient Search Input
User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Optional team API code resolved for the authenticated organization. Used to associate the patient search with a team.
defaultOverall search robustness level. Accepts Optimized, Thorough, Robust, or an integer from 1 to 100.
OptimizedWhen true, the downstream patient search pipeline also requests summarization work after the patient search is kicked off.
trueExample: trueFlag to indicate if this is a test request
falseExample: trueAt least one patient was successfully queued for processing
Request accepted. At least one patient search was queued. Top-level status is success if all items queued successfully and partial_success if some items failed immediately.
Status of the request
successPossible values: HTTP status code
202Possible values: Unique identifier associated with the request. Use this to chain subsequent retrieval and summarization API calls.
550e8400-e29b-41d4-a716-446655440000Whether any patient search is still processing
truePossible values: UTC timestamp for when the response was generated
2026-03-17T13:45:21.123456Request validation failed or all patient searches failed with client-side errors
Unauthorized
Patient selection could not be automated because multiple possible patient matches were found
Rate limit exceeded — the same patient was already searched within the last hour
Internal server error or all patient searches failed with server-side errors
POST /search-patient HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 502
{
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"api_code": "default",
"patient_metadata": [
{
"addresses": [
{
"street_address_line": "1100 Test Street",
"city": "Helena",
"state": "AL",
"postal_code": "35080",
"country": "US"
}
],
"demographics": {
"given_name": "Nwhinone",
"family_name": "Nwhinzzztestpatient",
"administrative_gender_code": "M",
"birth_time": "19810101",
"email": "patient@example.com",
"phone_number": "205-111-1111"
}
}
],
"robustness": "Optimized",
"summarize": true,
"test": true
}{
"status": "success",
"status_code": 202,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"processing": true,
"timestamp": "2026-03-17T13:45:21.123456",
"results": [
{
"status": "success",
"status_code": 202,
"patient_id": "patient123",
"pid": "patient123",
"given_name": "Nwhinone",
"family_name": "Nwhinzzztestpatient",
"birth_time": "19810101",
"administrative_gender_code": "M",
"processing": true,
"error": "No patient addresses found. Please retry with patient addresses."
}
]
}Test Patient Example
You can test patient search without querying the national health information exchanges by setting the field test:true. Below is the test patient demographics and address for simulating a search:
Important Notes
Patient Disambiguation Required
If the submitted patient demographics match multiple possible patients, Abstractive Health will not automatically choose a patient. For patient safety, the API returns a 409 response and does not start the HIE search.
The API does not return the possible patient matches. The search must be completed manually in the Abstractive Health UI.
ambiguous_patient_indices refers to the zero-based index of the submitted patient_metadata item that could not be safely resolved.
Retrieve Patient Documents
Description
After a few minutes, attempt retrieval of the patient documents in the requested format.
Method
POST
Route
https://api.abstractive.ai/retrieve-patient-docs
Success Status Code
200
Avg. Response Time (Success)
Varies based on robustness score from /search-patient:
• 20 → 180 seconds
• 70 → 240 seconds
• 100 → 480 seconds
Retrieves uploaded and processed patient documents as a presigned S3 URL
Input object to retrieve patient documents
Unique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Unique patient identifier (single ID or array of IDs)
9de61c87-b0ce-4d34-8785-dacb55408eea["patient123","patient456"]Flag to indicate if this is a test request
falseExample: trueAll documents successfully retrieved
Successful document retrieval response
Overall status of the request
HTTP status code
unique identifier associated with the request
whether processing is occurring
Documents still processing
Some documents retrieved, others failed or processing
Invalid request parameters
Unauthorized
Conversation_id not recognized
Internal server error
POST /retrieve-patient-docs HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
"test": true
}{
"status": "success",
"status_code": 200,
"conversation_id": "text",
"processing": false,
"results": [
{
"status": "success",
"status_code": 200,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "patient123",
"url": "https://s3.amazonaws.com/bucket/results.json?AWSAccessKeyId=...",
"expires_in": 3600,
"processing": false
}
]
}URL Retrieval and Directory Structure
If the retrieval is successful, you can download the zipped folder from the pre-signed URL.
Structure of the zipped folder
Output Document Information
Documents retrieved from the HIE (health information exchanges) are returned as CDAs, FHIR, PDFs, PNGs, TIFF, and JPEGs mime-type formats. For all CDA documents that Abstractive retrieves from the HIEs, we parse them through a CDA -> FHIR conversion engine. You can find documentation on FHIR here by HL7 foundation.
Subsequently, we parse all FHIR documents (which includes the CDAs converted to FHIR) into a proprietary JSON flat-file format for data standardization. Note that healthcare data is quite messy, so our format can sometimes reflect that messiness.
Any documents that are not CDA or FHIR are not converted to a JSON format and left in raw format.
Important Notes
Step 3. Bulk Document Upload (Optional)
Upload multiple PDF, JPEG/JPG, TIFF/tiff, PNG, CDA or FHIR documents to generate a medical summary from the documents themselves, or to include with the documents you retrieved from the HIEs (health information exchanges) in step 2. This step is for net new documents, you do not need to resend us the documents that you retrieved in step 2.
Description
Upload the documents you want to use to generate a medical summary or include with the documents you retrieved from /search-patient in Step 2
Method
POST
Route
https://api.abstractive.ai/upload-patient-docs
Success Status Code
200 or 202
Avg. Response Time (Success)
180 - 300 seconds
Input Parameters
Uploads patient documents (PDFs, CDA, FHIR) for processing and analysis. Supports two input modes - with existing patient_id or with patient_metadata for new patients
Upload Patient Documents Input - supports two modes (existing patient or new patient with metadata)
User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Optional conversation ID. If not provided, one will be generated
550e8400-e29b-41d4-a716-446655440000Existing patient ID (for Option 1)
9de61c87-b0ce-4d34-8785-dacb55408eeaDocuments successfully uploaded and processed
Successful document upload
Status of the request
successPossible values: HTTP status code
202Possible values: Unique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000Patient ID
patient123Number of files successfully processed
3Whether processing is occurring
trueDocuments uploaded and processing started
Invalid request
Unauthorized
Patient not found
Patient selection could not be automated because multiple possible patient matches were found
Internal server error
POST /upload-patient-docs HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 669
{
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
"patient_metadata": {
"addresses": [
{
"street_address_line": "1100 Test Street",
"city": "Helena",
"state": "AL",
"postal_code": "35080",
"country": "USA"
}
],
"demographics": {
"given_name": "Nwhinone",
"family_name": "Nwhinzzztestpatient",
"administrative_gender_code": "M",
"birth_time": "19810101",
"phone_number": "205-111-1111"
}
},
"files": {
"non_text": [
"JVBERi0xLjQKJdPr6eEKMSAwIG9iago..."
],
"cda": [
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0..."
],
"fhir": [
"eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50Iiwi..."
]
}
}{
"status": "success",
"status_code": 202,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "patient123",
"document_count": 3,
"processing": true
}Step 4. Request a Summary (From Patient Search and/or From Bulk Upload Documents)
Using the clinical documents retrieved from a patient search, along with any additional documents you choose to include, we generate a comprehensive medical summary that surfaces key clinical insights. The summary includes:
Medical history, past clinical events, family history, social history, allergies
Medications, labs, vitals
Radiology findings, follow-up recommendations, and care team information
Designed for clinical treatment workflows, our summaries support clinicians before a visit, during care handoffs, and at discharge and ensure clinicians have the right information at the right time.
In addition, each summary includes structured medical entities extracted from the record, including ICD-10, CPT, and HCC codes, enabling downstream use in risk adjustment, billing, and care coordination.
Description
Generate a medical summary based on the documents retrieved from patient search and/or bulk upload endpoints. You must either first call /search-patient or /upload-patient-docs API endpoints before accessing this endpoint.
Method
POST
Route
https://api.abstractive.ai/request-summary
Success Status Code
202
Avg. Response Time (Success)
3 - 5 seconds
Input Parameters
Requests a summary of an entire conversation containing patient documents
Input object to request a conversation summary
User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Unique patient identifier
9de61c87-b0ce-4d34-8785-dacb55408eeaUnique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000Flag to indicate if this is a test request
falseExample: trueProcessing started
Processing status for summary request
Status of the request
successPossible values: HTTP status code
202Possible values: Unique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000Unique patient identifier
patient123Whether processing is occurring
truePossible values: Missing required fields
Unauthorized
Internal server error
POST /request-summary HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"test": true
}{
"status": "success",
"status_code": 202,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "patient123",
"processing": true
}Important Notes
Step 5. Retrieve a Summary
Description
Retrieve the summary after requesting to create one through /request-summary API endpoint
Method
POST
Route
https://api.abstractive.ai/retrieve-summary
Success Status Code
200
Avg. Response Time (Success)
60 - 180 seconds
Input Parameters
Retrieves a completed conversation summary
Input object to retrieve a generated conversation summary
User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Unique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000Unique patient identifier
9de61c87-b0ce-4d34-8785-dacb55408eeaFlag to indicate if this is a test request
falseExample: trueSummary ready
Successful summary retrieval response
Status of the request
successPossible values: HTTP status code
200Possible values: Unique identifier associated with the request
550e8400-e29b-41d4-a716-446655440000Unique patient identifier
patient123Presigned URL to download summary
https://s3.amazonaws.com/bucket/summary.json?AWSAccessKeyId=...URL expiration time in seconds
3600Possible values: Whether URL is posted
truePossible values: Whether processing is occurring
Summary still processing
Missing required fields
Unauthorized
Conversation_id not recognized
Internal server error
POST /retrieve-summary HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
"test": true
}{
"status": "success",
"status_code": 200,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"patient_id": "patient123",
"url": "https://s3.amazonaws.com/bucket/summary.json?AWSAccessKeyId=...",
"expires_in": 3600,
"posted": true,
"processing": false
}Format of cleaned_text_notes/
AI Summary Format
If the retrieval is successful, you can download the json output from the pre-signed URL. It will come in the following format:
Summary Scoring
The scoring.SimilarityScores object in the response tells you how well each sentence in the AI summary is supported by the source documents. Every summary sentence is matched against every sentence in the source notes using a semantic similarity model. The final per-sentence score is a hybrid of two signals:
Semantic similarity (cosine similarity): Captures meaning — sentences that convey the same information in different words still score highly. This is the dominant factor.
Lexical overlap bonus: A small bonus is added when the summary and source sentence share the same exact words. This rewards verbatim evidence like lab values or drug names.
Each section (HPI, Labs, Vitals, etc.) contains:
OverallScore— the average score across all sentences in that section. Use this as a quick signal for how well-sourced a section is overall.Sentences— a map from each summary sentence to its best-matching source sentence and score. Use this to trace individual claims back to the original document.
0.85 – 1.0+
Very strong match — the source sentence directly supports the summary statement
0.65 – 0.85
Good match — closely related content, possibly paraphrased
0.45 – 0.65
Moderate — thematically related but not a direct source
Below 0.45
Weak — the AI may be synthesizing across multiple sources or inferring
Important Notes
Step 6. Push Back Treatment Documents
As part of using our patient search API, you are required to submit any new clinical treatment records within 7 days of your document retrieval. This requirement ensures compliance with the Carequality® framework and other national health information exchange (HIE) policies.
Our participation in these exchanges is governed by a principle of data reciprocity—meaning that in return for accessing clinical records, your organization must contribute new treatment documentation back into the network. This fosters a nationwide ecosystem of interoperability and care coordination.
The Abstractive Health team is here to support you. We’re happy to guide you through the process of formatting and submitting your documents back to the health information exchanges.
Push a document
Description
Send a new clinical treatment document to Abstractive Health
Method
POST
Route
https://api.abstractive.ai/push-document
Avg. Response Time (Success)
10 - 15 seconds
Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata
Push structured note data for CDA conversion and storage. Each summary item must include either patient_id or patient_metadata, and either summary_id or summary_edited.
User's API email
user@example.comOAuth token obtained from get-token route
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Flag to indicate if this is a test request
falseAll pushed documents completed successfully
All pushed documents completed successfully
Unique identifier associated with the request
UTC timestamp for when the response was generated
Combined message across pushed note results
Some pushed documents completed successfully while others failed
Validation failure
Unauthorized
Internal server error
POST /push-document HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 800
{
"user_api_email": "user@example.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"test": false,
"author": {
"given_name": "Alex",
"family_name": "Smith",
"authored_on": "20260317",
"npi": "1234567890",
"specialty": "Internal Medicine"
},
"summaries": [
{
"summary_id": "summary-123",
"patient_id": "patient123",
"patient_metadata": {
"addresses": [
{
"street_address_line": "1100 Test Street",
"city": "Helena",
"state": "AL",
"postal_code": "35080",
"country": "US"
}
],
"demographics": {
"given_name": "Nwhinone",
"family_name": "Nwhinzzztestpatient",
"administrative_gender_code": "M",
"birth_time": "19810101",
"email": "patient@example.com",
"phone_number": "205-111-1111"
}
},
"summary_assessment": "Follow-up note for chronic condition management.",
"summary_edited": "Patient is stable on current medication regimen.",
"summary_format": "text"
}
]
}{
"status": "success",
"status_code": 200,
"conversation_id": "text",
"processing": false,
"timestamp": "2026-01-01T00:00:00.000Z",
"message": "text",
"results": [
{
"status": "success",
"status_code": 200,
"processing": false,
"timestamp": "2026-01-01T00:00:00.000Z",
"patient_id": "patient123",
"document_count": 1,
"note_id": "note-123",
"summary_id": "summary-123",
"message": "Pushed document successfully",
"failure_reason": "text",
"error": "text"
}
]
}Important Notes
Question & Answering
Ask natural-language questions about a patient's clinical record and receive AI-generated answers grounded in the patient's documents. Each conversation is stateful — follow-up questions stay in context automatically.
Ask a Question
Description
Ask a clinical question about a patient's chart. Returns an AI-generated answer with source references from the patient's documents.
Method
POST
Route
https://api.abstractive.ai/ask
Success Status Code
200
Avg. Response Time (Success)
5 - 15 seconds
Ask a natural-language clinical question about a patient's chart. The response is generated using retrieval-augmented generation (RAG) over the patient's ingested clinical documents. Optionally pass a conversation_id to continue an existing conversation.
Request to ask a clinical question about a patient
API user email address
provider@hospital.orgAPI access token obtained from POST /get-token
eyJhbGciOiJSUzI1NiJ9...Internal patient identifier returned by POST /search-patient
3fa85f64-5717-4562-b3fc-2c963f66afa6Natural-language clinical question about the patient
What medications is the patient currently taking for hypertension?Conversation ID from a previous /ask response. Pass this to continue an existing conversation rather than starting a new one.
7c9e6679-7425-40de-944b-e07fc1f90ae7Controls how broadly the patient's chart is searched before answering. auto (default) lets the AI automatically select retrieval depth and response model based on the question — recommended for most use cases. direct performs a fast minimal lookup, best for simple targeted facts such as "When was the patient's last hospitalization?" complex performs maximum-depth retrieval across the full chart history, best for longitudinal questions such as "Show me all historical lab results." Manual overrides (direct and complex) require Q&A Mode Selection to be enabled for your organization; without it, requests proceed with auto mode and a subscription note is included in the response.
autoExample: autoPossible values: Answer generated successfully
Successful answer to a clinical question
successPossible values: 200AI-generated clinical answer grounded in the patient's chart
The patient is currently prescribed lisinopril 10 mg daily and amlodipine 5 mg daily.Conversation identifier. Pass this in subsequent /ask calls to continue the conversation, or in /get-alert-event follow-ups.
7c9e6679-7425-40de-944b-e07fc1f90ae7Unique identifier for this specific message
9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6dOptional subscription note. Present when a manual mode override was requested but Q&A Mode Selection is not enabled for the organization; the request proceeded with auto mode instead.
Manual mode selection is not enabled for your organization. This request proceeded with auto mode. Contact Abstractive Health to enable direct and complex mode overrides.Validation error
Unauthorized
Internal server error
POST /ask HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 279
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"patient_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"question": "What medications is the patient currently taking for hypertension?",
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"mode": "auto"
}{
"status": "success",
"status_code": 200,
"processing": false,
"answer": "The patient is currently prescribed lisinopril 10 mg daily and amlodipine 5 mg daily.",
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"message_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"mode_note": "Manual mode selection is not enabled for your organization. This request proceeded with auto mode. Contact Abstractive Health to enable direct and complex mode overrides.",
"sources": [
{
"content": "Patient reports taking lisinopril 10mg and amlodipine 5mg daily.",
"note_title": "Progress Note",
"timestamp": "2024-03-15T09:30:00Z"
}
]
}Important Notes
List Conversations
Description
List all question & answer conversations for the authenticated user, optionally filtered by patient.
Method
GET or POST
Route
https://api.abstractive.ai/list-conversations
Success Status Code
200
Avg. Response Time (Success)
~1 second
List Q&A conversations for the authenticated user, optionally filtered by patient.
Request to list Q&A conversations
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...Optional — filter conversations to a specific patient
3fa85f64-5717-4562-b3fc-2c963f66afa6Conversations retrieved
List of Q&A conversations
successPossible values: 200Unauthorized
Internal server error
POST /list-conversations HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 128
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"patient_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}{
"status": "success",
"status_code": 200,
"processing": false,
"conversations": [
{
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"title": "Hypertension medication review",
"updated_at": "2024-03-15T09:30:00Z"
}
]
}Get Conversation
Description
Retrieve the full message history of a specific conversation by its ID.
Method
GET or POST
Route
https://api.abstractive.ai/get-conversation
Success Status Code
200
Avg. Response Time (Success)
~1 second
Retrieve the full message history of a Q&A conversation.
Request to retrieve a full conversation
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...7c9e6679-7425-40de-944b-e07fc1f90ae7Conversation retrieved
Full message history of a Q&A conversation
successPossible values: 2007c9e6679-7425-40de-944b-e07fc1f90ae7Hypertension medication reviewValidation error
Unauthorized
Internal server error
POST /get-conversation HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 133
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}{
"status": "success",
"status_code": 200,
"processing": false,
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"title": "Hypertension medication review",
"messages": [
{
"role": "assistant",
"content": "The patient is currently prescribed lisinopril 10 mg daily.",
"created_at": "2024-03-15T09:30:00Z"
}
]
}Care Notifications
Care notifications are questions that are automatically answered for all your patients and are flagged if the patient meets the trigger criteria that you set. Each time a new patient summary is generated, all active care notifications evaluate automatically against that patient's chart. You can retrieve those results, read the AI-generated clinical response, and ask follow-up questions in the same conversation.
Create a Care Notification
Description
Create a new care notification for your organisation. It will run automatically on every new patient summary.
Method
POST
Route
https://api.abstractive.ai/create-alert
Success Status Code
200
Avg. Response Time (Success)
~1 second
Create a new care notification for the organisation. Care notifications are questions that are automatically answered for all your patients and are flagged if the patient meets the trigger criteria that you set. They run automatically after each patient summary is generated. A new version is created automatically on each edit — prior versions are archived.
Request to create a new care notification. The care notification will automatically run against every patient summary created after this point. Versioning is handled server-side.
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...Short display name for the care notification (max 30 characters)
Elevated HbA1cThe clinical question asked of the patient's chart by the AI. Write it as a specific, answerable question.
What is the patient's most recent HbA1c value?Expected answer format — numeric measurement or boolean yes/no
numberPossible values: Condition that triggers the notification. Use number_above, number_below, or number_between with numeric answer_type. Use boolean_true or boolean_false with boolean answer_type.
number_abovePossible values: Lower threshold. Required for number_above and number_between. Notification fires when the extracted value exceeds this.
7Upper threshold. Required for number_between.
9Unit of measurement for the extracted value
%When true, the AI also searches PubMed and clinical guidelines for additional context in the response.
falseCare notification created
Care notification created
successPossible values: 200Unique identifier for the newly created care notification
3fa85f64-5717-4562-b3fc-2c963f66afa6Validation error
Unauthorized
Internal server error
POST /create-alert HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"title": "Elevated HbA1c",
"question_text": "What is the patient's most recent HbA1c value?",
"answer_type": "number",
"trigger_type": "number_above",
"threshold_low": 7,
"threshold_high": 9,
"value_unit": "%",
"include_guidelines": false
}{
"status": "success",
"status_code": 200,
"processing": false,
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}Edit a Care Notification
Description
Update an existing care notification. A new version is created automatically; prior versions are archived.
Method
POST
Route
https://api.abstractive.ai/edit-alert
Success Status Code
200
Avg. Response Time (Success)
~1 second
Edit an existing care notification. A new version is created automatically and the previous version is archived. Only the original creator of the care notification may edit it.
Request to edit an existing care notification. A new version is created automatically and the previous version is archived. Only the original creator can edit. Pass only the fields you want to change alongside alert_id.
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...The care notification to update
3fa85f64-5717-4562-b3fc-2c963f66afa6Elevated HbA1c (updated)What is the patient's most recent HbA1c value in the past 12 months?7.5%Care notification updated
Care notification updated
successPossible values: 2003fa85f64-5717-4562-b3fc-2c963f66afa6ID of the newly created version
9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6dValidation error
Unauthorized
Internal server error
POST /edit-alert HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 384
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Elevated HbA1c (updated)",
"question_text": "What is the patient's most recent HbA1c value in the past 12 months?",
"answer_type": "number",
"trigger_type": "number_above",
"threshold_low": 7.5,
"threshold_high": 1,
"value_unit": "%",
"include_guidelines": false
}{
"status": "success",
"status_code": 200,
"processing": false,
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"version_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}Important Notes
List Care Notifications
Description
List all active care notifications for your organisation.
Method
GET or POST
Route
https://api.abstractive.ai/list-alerts
Success Status Code
200
Avg. Response Time (Success)
~1 second
List all care notifications configured for this organisation.
Request that requires authentication only — no additional parameters
API user email address
provider@hospital.orgAPI access token obtained from POST /get-token
eyJhbGciOiJSUzI1NiJ9...Care notifications retrieved
List of care notifications for the organisation
successPossible values: 200Unauthorized
Internal server error
POST /list-alerts HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 76
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9..."
}{
"status": "success",
"status_code": 200,
"processing": false,
"alerts": [
{
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"version_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"title": "Elevated HbA1c",
"answer_type": "number",
"trigger_type": "number_above",
"threshold_low": 7,
"threshold_high": null,
"value_unit": "%",
"enabled": true
}
]
}List Notification Results
Description
Retrieve care notification results for a patient. Returns one result per care notification per summary, showing whether the patient meets the trigger criteria and the extracted clinical value.
Method
GET or POST
Route
https://api.abstractive.ai/list-alert-events
Success Status Code
200
Avg. Response Time (Success)
~1 second
List care notification results for a patient. Returns the most recent result per notification. Care notifications are evaluated automatically when a new summary is created.
Request to list care notification results for a patient
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...The patient to retrieve notification results for
3fa85f64-5717-4562-b3fc-2c963f66afa6ISO 8601 timestamp. When provided, only events created after this time are returned. Use the dispatched_at value from POST /run-alerts to scope results to a specific run.
2024-03-15T09:00:00ZFilter to results for a specific care notification
8f14e45f-ceea-467a-a866-037b5d4b4b6bFilter to only triggered (true) or non-triggered (false) results
trueMaximum number of results to return (default 50, max 200)
50Pagination offset
Notification results retrieved
Most recent care notification result per notification for a patient
successPossible values: 200Validation error
Unauthorized
Internal server error
POST /list-alert-events HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 256
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"patient_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_after": "2024-03-15T09:00:00Z",
"alert_id": "8f14e45f-ceea-467a-a866-037b5d4b4b6b",
"triggered": true,
"limit": 50,
"offset": 0
}{
"status": "success",
"status_code": 200,
"processing": false,
"events": [
{
"event_id": "1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22",
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Elevated HbA1c",
"triggered": true,
"pending": false,
"fired_at": "2024-03-15T09:30:00Z",
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
]
}Get Notification Result
Description
Retrieve the full details of a single care notification result, including the AI-generated clinical response and supporting chart evidence.
Method
GET or POST
Route
https://api.abstractive.ai/get-alert-event
Success Status Code
200
Avg. Response Time (Success)
~1 second
Retrieve the full details of a care notification result, including the AI-generated clinical response and supporting chart evidence. Use the returned conversation_id with POST /ask to ask follow-up questions in the same conversation context.
Request to retrieve a specific care notification result
provider@hospital.orgeyJhbGciOiJSUzI1NiJ9...The event ID from a /list-alert-events response
1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22Notification result retrieved
Full detail of a care notification result
successPossible values: 200True if the evaluation is still in progress
1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c223fa85f64-5717-4562-b3fc-2c963f66afa6Elevated HbA1cWhether the patient meets the trigger criteria for this care notification
trueThe extracted value from the chart that was compared against the threshold. A number for numeric care notifications, a boolean for yes/no ones, or null if not yet available.
8.2Unit for numeric trigger values
%AI-generated clinical narrative summarising the finding
The patient's most recent HbA1c was 8.2% recorded on 2024-02-10, exceeding the 7.0% threshold.Continue the conversation with POST /ask using this ID to ask follow-up questions about this care notification finding.
7c9e6679-7425-40de-944b-e07fc1f90ae7ISO 8601 timestamp of the evaluation
2024-03-15T09:30:00ZValidation error
Unauthorized
Result not found
Internal server error
POST /get-alert-event HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 126
{
"user_api_email": "provider@hospital.org",
"token": "eyJhbGciOiJSUzI1NiJ9...",
"event_id": "1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22"
}{
"status": "success",
"status_code": 200,
"processing": false,
"event_id": "1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22",
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Elevated HbA1c",
"triggered": true,
"trigger_value": 8.2,
"value_unit": "%",
"response": "The patient's most recent HbA1c was 8.2% recorded on 2024-02-10, exceeding the 7.0% threshold.",
"conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"sources": [
{
"content": "Patient reports taking lisinopril 10mg and amlodipine 5mg daily.",
"note_title": "Progress Note",
"timestamp": "2024-03-15T09:30:00Z"
}
],
"fired_at": "2024-03-15T09:30:00Z"
}Important Notes
Delete a Care Notification
Description
Permanently archive a care notification. Archived notifications stop running automatically and no longer appear in list results. Only the creator can delete a notification. The action is idempotent.
Method
POST
Route
https://api.abstractive.ai/delete-alert
Success Status Code
200
Avg. Response Time (Success)
~1 second
Permanently archive a care notification. Archived notifications stop evaluating automatically and are hidden from list results. Only the original creator of the notification can delete it. The action is idempotent — calling it on an already-archived notification returns success.
Input object to archive a care notification
Your API user email address
developer@yourorg.comYour API authentication token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...UUID of the care notification to archive
3fa85f64-5717-4562-b3fc-2c963f66afa6Care notification archived
Confirmation that the care notification has been archived
success200Always true on success
truePresent and true if the notification was already archived before this call
Validation error
Unauthorized
Forbidden — caller is not the owner of this notification
Care notification not found
Internal server error
POST /delete-alert HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 142
{
"user_api_email": "developer@yourorg.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"alert_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}{
"status": "success",
"status_code": 200,
"processing": false,
"archived": true,
"already_archived": false
}Important Notes
Run Care Notifications
Description
Manually trigger all active care notifications for a single patient, all patients in a team, or all patients in your organisation. Evaluations run asynchronously — results appear in /list-alert-events and your webhook once complete.
Method
POST
Route
https://api.abstractive.ai/run-alerts
Success Status Code
200
Avg. Response Time (Success)
~1 second
Manually trigger all active care notifications for a single patient, all patients in a team, or all patients in your organisation. Evaluations run asynchronously — this endpoint returns as soon as all jobs are queued. Results appear in /list-alert-events and your configured webhook once each evaluation completes. Supply exactly one of patient_id, team_api_code, or run_for_org per call. For team and org scopes, results are capped at 50 patients per call; check the truncated field to determine if more remain.
Input object to trigger all active care notifications for a patient, team, or entire organisation. Supply exactly one of patient_id, team_api_code, or run_for_org.
Your API user email address
developer@yourorg.comYour API authentication token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Run all active notifications for a single patient
pid_abc123Run all active notifications for every patient on this team. Use the team's human-readable api_code (not the UUID team_id).
cardiology-eastRun all active notifications for every patient in the organisation. Capped at 50 patients per call — check the truncated field.
Alert jobs dispatched
Confirmation that care notification jobs have been dispatched
success200Total number of individual alert evaluation jobs fired (patients × notifications)
12Total matching patients found before the 50-patient cap was applied
15True if the patient count exceeded 50 and only the first 50 were processed. Call again to process the remaining patients.
ISO 8601 UTC timestamp of when jobs were dispatched. Pass this as created_after to POST /list-alert-events to scope results to only this run.
2024-03-15T09:00:00.123456ZValidation error
Unauthorized
Internal server error
POST /run-alerts HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 172
{
"user_api_email": "developer@yourorg.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"patient_id": "pid_abc123",
"team_api_code": "cardiology-east",
"run_for_org": false
}{
"status": "success",
"status_code": 200,
"processing": false,
"dispatched": 12,
"total_patients": 15,
"truncated": false,
"dispatched_at": "2024-03-15T09:00:00.123456Z"
}Important Notes
Set Webhook (Callback URL)
Description
Configure a callback URL for your organisation. When set, a POST request is sent to this URL automatically each time a care notification evaluation completes.
Method
POST
Route
https://api.abstractive.ai/set-webhook
Success Status Code
200
Avg. Response Time (Success)
~1 second
Set or clear the care notification callback webhook URL for the organisation. When configured, a POST request is automatically sent to this URL each time a care notification evaluation completes, containing the result and AI-generated clinical response. Pass null or omit webhook_url to remove a previously configured webhook.
Input object to set or clear the care notification callback webhook URL
Your API user email address
developer@yourorg.comYour API authentication token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...HTTPS URL to receive care notification result payloads. Omit or pass null to remove the webhook. The URL must be publicly reachable and respond with a 2xx status code.
https://yourapp.example.com/webhooks/care-notificationsWebhook URL updated
Confirmation of the webhook URL update
success200The webhook URL that was stored, or null if removed
https://yourapp.example.com/webhooks/cds-alertsValidation error
Unauthorized
Internal server error
POST /set-webhook HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 164
{
"user_api_email": "developer@yourorg.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"webhook_url": "https://yourapp.example.com/webhooks/care-notifications"
}{
"status": "success",
"status_code": 200,
"webhook_url": "https://yourapp.example.com/webhooks/cds-alerts"
}Get Webhook (Callback URL)
Description
Retrieve the care notification webhook URL currently configured for your organisation.
Method
GET or POST
Route
https://api.abstractive.ai/get-webhook
Success Status Code
200
Avg. Response Time (Success)
~1 second
Retrieve the care notification webhook URL currently configured for your organisation. Returns null if no webhook has been set.
Input object to retrieve the configured webhook URL
Your API user email address
developer@yourorg.comYour API authentication token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Webhook URL retrieved
The currently configured care notification webhook URL for the organisation
success200The configured webhook URL, or null if none has been set
https://yourapp.example.com/webhooks/care-notificationsUnauthorized
Internal server error
POST /get-webhook HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 92
{
"user_api_email": "developer@yourorg.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{
"status": "success",
"status_code": 200,
"processing": false,
"webhook_url": "https://yourapp.example.com/webhooks/care-notifications"
}Webhook Payload
When a care notification evaluation completes, Abstractive POSTs the following JSON to your callback URL:
Important Notes
Last updated