Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

👾API Reference Docs

All requests need to route to https://api.abstractive.ai base URL

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

post

Authenticates user credentials and returns an access token

Body

Input object to obtain token

user_api_emailstringRequired

User's API email

Example: user@example.com
username_apistringOptional

User's API username. Optional, defaults to user_api_email

Example: user@example.com
user_api_passwordstringRequired

User's API password

Example: password123
Responses
200

Success

application/json

Success token response

statusstring · enumOptional

Status of the request

Example: successPossible values:
status_codeinteger · enumOptional

HTTP status code

Example: 200Possible values:
access_tokenstringOptional

OAuth token for user

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
post/get-token
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

  • Only get a token when necessary

  • Make sure you have an active token before requesting a summary

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)

post

Searches for patients across multiple EHR systems based on provided metadata

Body

Patient Search Input

user_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api_codestringOptional

Optional team API code resolved for the authenticated organization. Used to associate the patient search with a team.

Example: default
robustnessstringOptional

Overall search robustness level. Accepts Optimized, Thorough, Robust, or an integer from 1 to 100.

Example: Optimized
summarizebooleanOptional

When true, the downstream patient search pipeline also requests summarization work after the patient search is kicked off.

Default: falseExample: true
testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true
Responses
202

At least one patient was successfully queued for processing

application/json

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.

statusstring · enumOptional

Status of the request

Example: successPossible values:
status_codeinteger · enumOptional

HTTP status code

Example: 202Possible values:
conversation_idstringOptional

Unique identifier associated with the request. Use this to chain subsequent retrieval and summarization API calls.

Example: 550e8400-e29b-41d4-a716-446655440000
processingboolean · enumOptional

Whether any patient search is still processing

Example: truePossible values:
timestampstring · date-timeOptional

UTC timestamp for when the response was generated

Example: 2026-03-17T13:45:21.123456
post/search-patient
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

  • Sending more than 5 sets of patient metadata will not result in error; sending 0 sets might result in error.

  • Make sure all patient metadata belongs to the same individual

  • The same patient cannot be searched more than once per 10 minute window. Re-searching a patient within the 1-hour cooldown window will return a 429 status code with the blocked patients (pid, given_name, family_name) in rate_limited_patients.

  • If Abstractive Health cannot safely automate patient selection because the submitted demographics match multiple possible patients, the API will return 409 patient_disambiguation_required. No Health Information Exchange search is started. The user must perform the search manually in the Abstractive Health UI.

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

post

Retrieves uploaded and processed patient documents as a presigned S3 URL

Body

Input object to retrieve patient documents

conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
user_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
patient_idone ofRequired

Unique patient identifier (single ID or array of IDs)

stringOptionalExample: 9de61c87-b0ce-4d34-8785-dacb55408eea
or
string[]OptionalExample: ["patient123","patient456"]
testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true
Responses
200

All documents successfully retrieved

application/json

Successful document retrieval response

statusstring · enumOptional

Overall status of the request

Possible values:
status_codeinteger · enumOptional

HTTP status code

Possible values:
conversation_idstringOptional

unique identifier associated with the request

processingboolean · enumOptional

whether processing is occurring

Possible values:
post/retrieve-patient-docs
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

Mimetype of the response will always be JSON even if CDA is requested.

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

post

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

Body

Upload Patient Documents Input - supports two modes (existing patient or new patient with metadata)

user_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
conversation_idstringOptional

Optional conversation ID. If not provided, one will be generated

Example: 550e8400-e29b-41d4-a716-446655440000
patient_idstringOptional

Existing patient ID (for Option 1)

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea
Responses
200

Documents successfully uploaded and processed

application/json

Successful document upload

statusstring · enumOptional

Status of the request

Example: successPossible values:
status_codeinteger · enumOptional

HTTP status code

Example: 202Possible values:
conversation_idstringOptional

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
patient_idstringOptional

Patient ID

Example: patient123
document_countintegerOptional

Number of files successfully processed

Example: 3
processingbooleanOptional

Whether processing is occurring

Example: true
post/upload-patient-docs
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
}

Note: When uploading non-text documents (PDFs, jpegs, TIFFs, pngs), you will receive a 202 status code as these files will have to be parsed and processed first.

If you request a summary while the documents are still processing, you will receive a 409 status code error. Please allow 3-5 minutes of processing window before requesting a summary.

If patient_metadata is provided and Abstractive Health cannot safely automate patient selection because the demographics match multiple possible patients, the API returns 409 patient_disambiguation_required. No upload processing is started for that unresolved patient. The search must be completed manually in the Abstractive Health UI using the manual_search_url returned in the response.

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

post

Requests a summary of an entire conversation containing patient documents

Body

Input object to request a conversation summary

user_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
patient_idstringRequired

Unique patient identifier

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea
conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true
Responses
202

Processing started

application/json

Processing status for summary request

statusstring · enumOptional

Status of the request

Example: successPossible values:
status_codeinteger · enumOptional

HTTP status code

Example: 202Possible values:
conversation_idstringOptional

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
patient_idstringOptional

Unique patient identifier

Example: patient123
processingboolean · enumOptional

Whether processing is occurring

Example: truePossible values:
post/request-summary
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

Limit summary requests to 1 every 30 seconds.

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

post

Retrieves a completed conversation summary

Body

Input object to retrieve a generated conversation summary

user_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
patient_idstringRequired

Unique patient identifier

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea
testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true
Responses
200

Summary ready

application/json

Successful summary retrieval response

statusstring · enumOptional

Status of the request

Example: successPossible values:
status_codeinteger · enumOptional

HTTP status code

Example: 200Possible values:
conversation_idstringOptional

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000
patient_idstringOptional

Unique patient identifier

Example: patient123
urlstringOptional

Presigned URL to download summary

Example: https://s3.amazonaws.com/bucket/summary.json?AWSAccessKeyId=...
expires_ininteger · enumOptional

URL expiration time in seconds

Example: 3600Possible values:
postedboolean · enumOptional

Whether URL is posted

Example: truePossible values:
processingboolean · enumOptional

Whether processing is occurring

Possible values:
post/retrieve-summary
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.

Score range
Interpretation

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

Scores can exceed 1.0 when the lexical overlap bonus is added to a high cosine similarity. This is expected behavior.

Important Notes

  • You can retrieve a summary every 15 seconds.

  • We recommend not retrieving the same summary more than 30 times

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

Parameter Name
Description

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

post

Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata

Body

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_api_emailstringRequired

User's API email

Example: user@example.com
tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
testbooleanOptional

Flag to indicate if this is a test request

Default: false
Responses
200

All pushed documents completed successfully

application/json

All pushed documents completed successfully

statusstring · enumOptionalPossible values:
status_codeinteger · enumOptionalPossible values:
conversation_idstringOptional

Unique identifier associated with the request

processingboolean · enumOptionalPossible values:
timestampstring · date-timeOptional

UTC timestamp for when the response was generated

messagestringOptional

Combined message across pushed note results

post/push-document
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

  • You are required to return a clinical treatment document for every patient retrieved from Carequality® within 7 days.

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

post

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.

Body

Request to ask a clinical question about a patient

user_api_emailstringRequired

API user email address

Example: provider@hospital.org
tokenstringRequired

API access token obtained from POST /get-token

Example: eyJhbGciOiJSUzI1NiJ9...
patient_idstringRequired

Internal patient identifier returned by POST /search-patient

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
questionstringRequired

Natural-language clinical question about the patient

Example: What medications is the patient currently taking for hypertension?
conversation_idstringOptional

Conversation ID from a previous /ask response. Pass this to continue an existing conversation rather than starting a new one.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
modestring · enumOptional

Controls 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.

Default: autoExample: autoPossible values:
Responses
200

Answer generated successfully

application/json

Successful answer to a clinical question

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
answerstringOptional

AI-generated clinical answer grounded in the patient's chart

Example: The patient is currently prescribed lisinopril 10 mg daily and amlodipine 5 mg daily.
conversation_idstringOptional

Conversation identifier. Pass this in subsequent /ask calls to continue the conversation, or in /get-alert-event follow-ups.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
message_idstringOptional

Unique identifier for this specific message

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
mode_notestringOptional

Optional 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.

Example: 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.
post/ask
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

  • Pass the conversation_id from a previous /ask response to continue the conversation in the same context.

  • A patient summary must exist for the patient before asking questions — call /request-summary first.

  • Use mode to control how broadly the chart is searched. auto (default) lets the AI automatically choose retrieval depth and model based on your question — suitable for most use cases. direct performs a fast, minimal lookup best for simple targeted facts. complex performs maximum-depth retrieval across the full chart history, best for longitudinal questions. Manual mode overrides (direct and complex) require Q&A Mode Selection to be enabled for the organization; without it, requests proceed with auto mode and the response includes a mode_note.

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

post

List Q&A conversations for the authenticated user, optionally filtered by patient.

Body

Request to list Q&A conversations

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
patient_idstringOptional

Optional — filter conversations to a specific patient

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Responses
200

Conversations retrieved

application/json

List of Q&A conversations

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
post/list-conversations
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

post

Retrieve the full message history of a Q&A conversation.

Body

Request to retrieve a full conversation

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
conversation_idstringRequiredExample: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Responses
200

Conversation retrieved

application/json

Full message history of a Q&A conversation

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
conversation_idstringOptionalExample: 7c9e6679-7425-40de-944b-e07fc1f90ae7
titlestringOptionalExample: Hypertension medication review
post/get-conversation
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

post

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.

Body

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.

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
titlestringRequired

Short display name for the care notification (max 30 characters)

Example: Elevated HbA1c
question_textstringRequired

The clinical question asked of the patient's chart by the AI. Write it as a specific, answerable question.

Example: What is the patient's most recent HbA1c value?
answer_typestring · enumRequired

Expected answer format — numeric measurement or boolean yes/no

Example: numberPossible values:
trigger_typestring · enumRequired

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.

Example: number_abovePossible values:
threshold_lownumberOptional

Lower threshold. Required for number_above and number_between. Notification fires when the extracted value exceeds this.

Example: 7
threshold_highnumberOptional

Upper threshold. Required for number_between.

Example: 9
value_unitstringOptional

Unit of measurement for the extracted value

Example: %
include_guidelinesbooleanOptional

When true, the AI also searches PubMed and clinical guidelines for additional context in the response.

Default: false
Responses
200

Care notification created

application/json

Care notification created

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
alert_idstringOptional

Unique identifier for the newly created care notification

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
post/create-alert
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

post

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.

Body

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.

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
alert_idstringRequired

The care notification to update

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
titlestringOptionalExample: Elevated HbA1c (updated)
question_textstringOptionalExample: What is the patient's most recent HbA1c value in the past 12 months?
answer_typestring · enumOptionalPossible values:
trigger_typestring · enumOptionalPossible values:
threshold_lownumberOptionalExample: 7.5
threshold_highnumberOptional
value_unitstringOptionalExample: %
include_guidelinesbooleanOptional
Responses
200

Care notification updated

application/json

Care notification updated

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
alert_idstringOptionalExample: 3fa85f64-5717-4562-b3fc-2c963f66afa6
version_idstringOptional

ID of the newly created version

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
post/edit-alert
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

  • Versioning is handled server-side — you do not need to manage version numbers. Each edit creates a new version and automatically archives the previous one.

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

post

List all care notifications configured for this organisation.

Body

Request that requires authentication only — no additional parameters

user_api_emailstringRequired

API user email address

Example: provider@hospital.org
tokenstringRequired

API access token obtained from POST /get-token

Example: eyJhbGciOiJSUzI1NiJ9...
Responses
200

Care notifications retrieved

application/json

List of care notifications for the organisation

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
post/list-alerts
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

post

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.

Body

Request to list care notification results for a patient

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
patient_idstringRequired

The patient to retrieve notification results for

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
created_afterstringOptional

ISO 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.

Example: 2024-03-15T09:00:00Z
alert_idstringOptional

Filter to results for a specific care notification

Example: 8f14e45f-ceea-467a-a866-037b5d4b4b6b
triggeredbooleanOptional

Filter to only triggered (true) or non-triggered (false) results

Example: true
limitintegerOptional

Maximum number of results to return (default 50, max 200)

Example: 50
offsetintegerOptional

Pagination offset

Responses
200

Notification results retrieved

application/json

Most recent care notification result per notification for a patient

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional
post/list-alert-events
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

post

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.

Body

Request to retrieve a specific care notification result

user_api_emailstringRequiredExample: provider@hospital.org
tokenstringRequiredExample: eyJhbGciOiJSUzI1NiJ9...
event_idstringRequired

The event ID from a /list-alert-events response

Example: 1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22
Responses
200

Notification result retrieved

application/json

Full detail of a care notification result

statusstring · enumOptionalExample: successPossible values:
status_codeintegerOptionalExample: 200
processingbooleanOptional

True if the evaluation is still in progress

event_idstringOptionalExample: 1c72c8c6-a6e2-4e3d-9bce-5b78ef7d8c22
alert_idstringOptionalExample: 3fa85f64-5717-4562-b3fc-2c963f66afa6
titlestringOptionalExample: Elevated HbA1c
triggeredbooleanOptional

Whether the patient meets the trigger criteria for this care notification

Example: true
trigger_valueanyOptional

The 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.

Example: 8.2
value_unitstringOptional

Unit for numeric trigger values

Example: %
responsestringOptional

AI-generated clinical narrative summarising the finding

Example: The patient's most recent HbA1c was 8.2% recorded on 2024-02-10, exceeding the 7.0% threshold.
conversation_idstringOptional

Continue the conversation with POST /ask using this ID to ask follow-up questions about this care notification finding.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
fired_atstringOptional

ISO 8601 timestamp of the evaluation

Example: 2024-03-15T09:30:00Z
post/get-alert-event
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

  • Use the conversation_id from this response with POST /ask to ask follow-up questions about the care notification finding.

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

post

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.

Body

Input object to archive a care notification

user_api_emailstringRequired

Your API user email address

Example: developer@yourorg.com
tokenstringRequired

Your API authentication token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
alert_idstringRequired

UUID of the care notification to archive

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Responses
200

Care notification archived

application/json

Confirmation that the care notification has been archived

statusstringOptionalExample: success
status_codeintegerOptionalExample: 200
processingbooleanOptional
archivedbooleanOptional

Always true on success

Example: true
already_archivedbooleanOptional

Present and true if the notification was already archived before this call

post/delete-alert
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

  • Only the user who created the notification can delete it.

  • Deleting is irreversible — previously recorded results remain accessible via /list-alert-events and /get-alert-event, but the notification will no longer evaluate on new summaries.

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

post

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.

Body

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.

user_api_emailstringRequired

Your API user email address

Example: developer@yourorg.com
tokenstringRequired

Your API authentication token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
patient_idstringOptional

Run all active notifications for a single patient

Example: pid_abc123
team_api_codestringOptional

Run all active notifications for every patient on this team. Use the team's human-readable api_code (not the UUID team_id).

Example: cardiology-east
run_for_orgbooleanOptional

Run all active notifications for every patient in the organisation. Capped at 50 patients per call — check the truncated field.

Responses
200

Alert jobs dispatched

application/json

Confirmation that care notification jobs have been dispatched

statusstringOptionalExample: success
status_codeintegerOptionalExample: 200
processingbooleanOptional
dispatchedintegerOptional

Total number of individual alert evaluation jobs fired (patients × notifications)

Example: 12
total_patientsintegerOptional

Total matching patients found before the 50-patient cap was applied

Example: 15
truncatedbooleanOptional

True if the patient count exceeded 50 and only the first 50 were processed. Call again to process the remaining patients.

dispatched_atstringOptional

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.

Example: 2024-03-15T09:00:00.123456Z
post/run-alerts
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

  • Supply exactly one of patient_id, team_api_code, or run_for_org: true per call.

  • For team and org scopes, results are capped at 50 patients per call. If truncated is true in the response, call again — the next batch will be dispatched for the remaining patients.

  • Evaluations are dispatched immediately and run asynchronously. The endpoint returns as soon as all jobs are queued, typically in under a second.

  • Care notifications run automatically after every new summary — use this endpoint to re-run on existing patients or when you add a new notification and want to backfill results.

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

post

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.

Body

Input object to set or clear the care notification callback webhook URL

user_api_emailstringRequired

Your API user email address

Example: developer@yourorg.com
tokenstringRequired

Your API authentication token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
webhook_urlstringOptional

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.

Example: https://yourapp.example.com/webhooks/care-notifications
Responses
200

Webhook URL updated

application/json

Confirmation of the webhook URL update

statusstringOptionalExample: success
status_codeintegerOptionalExample: 200
webhook_urlstringOptional

The webhook URL that was stored, or null if removed

Example: https://yourapp.example.com/webhooks/cds-alerts
post/set-webhook
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

post

Retrieve the care notification webhook URL currently configured for your organisation. Returns null if no webhook has been set.

Body

Input object to retrieve the configured webhook URL

user_api_emailstringRequired

Your API user email address

Example: developer@yourorg.com
tokenstringRequired

Your API authentication token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Responses
200

Webhook URL retrieved

application/json

The currently configured care notification webhook URL for the organisation

statusstringOptionalExample: success
status_codeintegerOptionalExample: 200
processingbooleanOptional
webhook_urlstringOptional

The configured webhook URL, or null if none has been set

Example: https://yourapp.example.com/webhooks/care-notifications
post/get-webhook
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

  • Your endpoint must respond with a 2xx status code. Non-2xx responses are logged but do not block the alert evaluation.

  • Pass null for webhook_url to remove a previously configured webhook.

  • The conversation_id in the webhook payload can be passed to POST /ask for follow-up questions about the care notification finding.

  • patient_name, patient_dob, and patient_gender are populated from the patient's most recent summary. They may be null if no summary has been generated yet.

Last updated