# API Reference Docs {% hint style="info" %} All requests need to route to `https://api.abstractive.ai` base URL {% endhint %} ## 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.
DescriptionRetrieves an authentication token
MethodPOST
Routehttps://api.abstractive.ai/get-token
Success Status Code200
LimitationsAccess token valid for 60 minutes
Avg. Response Time (Success)~1 second
## POST /get-token > Authenticates user credentials and returns an access token ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/get-token":{"post":{"tags":["get-token"],"description":"Authenticates user credentials and returns an access token","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}}}}},"components":{"schemas":{"TokenResponse":{"description":"Success token response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"access_token":{"type":"string","description":"OAuth token for user"}}},"TokenFailure":{"description":"Failed token response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"Type of error"},"missing_fields":{"type":"array","description":"Missing required fields (if validation error)","items":{"type":"string"}}}},"TokenRequest":{"description":"Input object to obtain token","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"username_api":{"type":"string","description":"User's API username. Optional, defaults to user_api_email"},"user_api_password":{"type":"string","description":"User's API password"}},"required":["user_api_email","user_api_password"]}}}} ``` #### Important Notes {% hint style="info" %} * Only get a token when necessary * Make sure you have an active token before requesting a summary {% endhint %} ## 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
DescriptionProvide a set of patient metadata to kick off an asynchronous Health Information Exchange (HIE) search.
MethodPOST
Routehttps://api.abstractive.ai/search-patient
Success Status Code202
LimitationsWe will take up to 5 patients per request.
Avg. Response Time (Success)3 - 5 seconds (time to 202 response)
## POST /search-patient > Searches for patients across multiple EHR systems based on provided metadata ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/search-patient":{"post":{"tags":["search-patient"],"description":"Searches for patients across multiple EHR systems based on provided metadata","responses":{"202":{"description":"At least one patient was successfully queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchAccepted"}}}},"400":{"description":"Request validation failed or all patient searches failed with client-side errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchAuthenticationFailure"}}}},"429":{"description":"Rate limit exceeded — the same patient was already searched within the last hour","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchRateLimitError"}}}},"500":{"description":"Internal server error or all patient searches failed with server-side errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchRequest"}}}}}}},"components":{"schemas":{"PatientSearchAccepted":{"description":"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.","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success","partial_success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request. Use this to chain subsequent retrieval and summarization API calls."},"processing":{"type":"boolean","description":"Whether any patient search is still processing","enum":[true]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"results":{"type":"array","description":"Array of per-patient search results. Each item reports its own status, processing state, patient identifiers, and any immediate failure detail.","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchResult":{"description":"Result for a single patient search. Successful items include processing=true and patient identifiers. Failed items include error and a 4xx/5xx status_code.","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's search","enum":["success","failure"]},"status_code":{"type":"integer","description":"HTTP status code for this patient result"},"patient_id":{"type":"string","description":"Unique patient identifier assigned or matched by Abstractive Health for this organization"},"pid":{"type":"string","description":"Internal patient identifier. Matches patient_id when available."},"given_name":{"type":"string","description":"Patient given name echoed from the request"},"family_name":{"type":"string","description":"Patient family name echoed from the request"},"birth_time":{"type":"string","description":"Patient birth date echoed from the request in YYYYMMDD format"},"administrative_gender_code":{"type":"string","description":"Patient gender code echoed from the request","enum":["M","F"]},"processing":{"type":"boolean","description":"Whether this patient is currently being processed"},"error":{"type":"string","description":"Error message for failed patient searches"}}},"PatientSearchValidationFailure":{"description":"Patient search validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}},"invalid_fields":{"type":"object","description":"Invalid fields keyed by field name with validation messages","additionalProperties":{"type":"string"}},"results":{"type":"array","description":"Array of search results for each patient","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchAuthenticationFailure":{"description":"Patient search authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"}}},"PatientSearchRateLimitError":{"description":"Rate limit exceeded — the same patient was already searched within the last hour","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[429]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"},"rate_limited_patients":{"type":"array","description":"List of patients that triggered the rate limit","items":{"type":"object","properties":{"pid":{"type":"string","description":"Patient ID"},"given_name":{"type":"string","description":"Patient first name"},"family_name":{"type":"string","description":"Patient last name"}}}}}},"PatientSearchInternalServerError":{"description":"Patient search internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"},"error_details":{"type":"string","description":"Additional internal error details when available"},"results":{"type":"array","description":"Array of search results for each patient","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchRequest":{"description":"Patient Search Input","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"api_code":{"type":"string","description":"Optional team API code resolved for the authenticated organization. Used to associate the patient search with a team."},"patient_metadata":{"type":"array","description":"List of patients and their metadata. The API also accepts a single patient metadata object in this same shape. The public documentation recommends sending at most 5 patients per request.","items":{"$ref":"#/components/schemas/PatientSearchMetadata"}},"robustness":{"description":"Overall search robustness level. Accepts Optimized, Thorough, Robust, or an integer from 1 to 100.","type":"string"},"summarize":{"type":"boolean","description":"When true, the downstream patient search pipeline also requests summarization work after the patient search is kicked off.","default":false},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","patient_metadata"]},"PatientSearchMetadata":{"description":"Patient metadata used for patient search. Demographics are required. Addresses are optional but materially improve matching quality.","type":"object","properties":{"addresses":{"type":"array","description":"List of patient addresses. If provided, each item must include all address fields below.","items":{"$ref":"#/components/schemas/PatientSearchAddress"}},"demographics":{"$ref":"#/components/schemas/PatientSearchDemographics"}},"required":["demographics"]},"PatientSearchAddress":{"description":"Patient address used for patient matching. Include places where the patient has lived throughout their life when available.","type":"object","properties":{"street_address_line":{"type":"string","description":"Street address where the patient lived or currently lives"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State or province code, typically a two-letter U.S. abbreviation such as NY"},"postal_code":{"type":"string","description":"Postal or ZIP code"},"country":{"type":"string","description":"Country code for the address. Current records are limited to the United States."}},"required":["street_address_line","city","state","postal_code","country"]},"PatientSearchDemographics":{"description":"Patient demographic details","type":"object","properties":{"given_name":{"type":"string","description":"Patient's given name. Include middle names here when available."},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient gender code","enum":["M","F"]},"birth_time":{"type":"string","description":"Patient birth date in YYYYMMDD format","pattern":"^\\d{8}$"},"email":{"type":"string","description":"Patient's email address"},"phone_number":{"type":"string","description":"Patient phone number, typically in XXX-XXX-XXXX format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}}} ``` #### 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: ```json // Patient search with test patient example { "user_api_email": "user@example.com", "token": "xxxxxxxxxx", "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" } } ], "robustness": "20", "test": true } * = required (optional parameters can be excluded from request) ``` #### Important Notes {% hint style="info" %} * 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 5 minute wondow. 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`. {% endhint %} ### Retrieve Patient Documents
DescriptionAfter a few minutes, attempt retrieval of the patient documents in the requested format.
MethodPOST
Routehttps://api.abstractive.ai/retrieve-patient-docs
Success Status Code200
Avg. Response Time (Success)Varies based on robustness score from /search-patient:
• 20 → 180 seconds
• 70 → 240 seconds
• 100 → 480 seconds
## POST /retrieve-patient-docs > Retrieves uploaded and processed patient documents as a presigned S3 URL ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/retrieve-patient-docs":{"post":{"tags":["retrieve-patient-docs"],"description":"Retrieves uploaded and processed patient documents as a presigned S3 URL","responses":{"200":{"description":"All documents successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalSuccess"}}}},"202":{"description":"Documents still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalProcessing"}}}},"207":{"description":"Some documents retrieved, others failed or processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalPartialSuccess"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalAuthenticationFailure"}}}},"404":{"description":"Conversation_id not recognized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalNotFoundFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalRequest"}}}}}}},"components":{"schemas":{"SearchRetrievalSuccess":{"description":"Successful document retrieval response","type":"object","properties":{"status":{"type":"string","description":"Overall status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResultSuccess"}}}},"PatientDocumentResultSuccess":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"}}},"SearchRetrievalProcessing":{"description":"Processing status for document retrieval","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["processing"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[true]},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResultProcessing"}}}},"PatientDocumentResultProcessing":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"}}},"SearchRetrievalPartialSuccess":{"description":"Partial success - some patients succeeded, others failed or processing","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["partial_success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[207]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring"},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"oneOf":[{"$ref":"#/components/schemas/PatientDocumentResultPartialSuccess"},{"$ref":"#/components/schemas/PatientDocumentResultProcessing"},{"$ref":"#/components/schemas/PatientDocumentResultFailure"}]}}}},"PatientDocumentResultPartialSuccess":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"PatientDocumentResultFailure":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"SearchRetrievalValidationFailure":{"description":"Search retrieval validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["ValidationError"]},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResult"}}}},"PatientDocumentResult":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"SearchRetrievalAuthenticationFailure":{"description":"Search retrieval authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["AuthenticationError"]}}},"SearchRetrievalNotFoundFailure":{"description":"Search retrieval not found failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[404]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["NotFoundError"]}}},"SearchRetrievalInternalServerError":{"description":"Search retrieval internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["InternalServerError"]}}},"SearchRetrievalRequest":{"description":"Input object to retrieve patient documents","type":"object","properties":{"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"patient_id":{"description":"Unique patient identifier (single ID or array of IDs)","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["conversation_id","user_api_email","token","patient_id"]}}}} ``` #### 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 ``` {conversation_id}.zip    ├── cda    │   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.xml    │   └── ...more cda documents...    ├── fhir    │   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.json    │   └── ...more FHIR json documents...    ├── non_text    | ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.pdf    | └── ...more non-text documents (jpeg/TIFF/png/pdf)...    ├── converted_text_notes    | ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.pdf    | └── ...more text notes converted to PDF format for easy viewing...    └── cleaned_text_notes       ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.json       └── ...more parsed and cleaned medical documents... ``` #### 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](https://build.fhir.org/) 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. ```json # Format of the cleaned_text_notes JSON { "section_content": { "Document Title": "", "Document Date": "", "Encounter Type": "", "Reason for Visit": "", "Allergies": [], "Immunizations": [], "Medications": [], "Vitals": [], "Labs": [], "Images": [], "Procedures": [], "Location": "", "Location Type": "", "Medical History": [], "Social History": "", "Family History": [], "Document Text": [], "Providers": [""], "Organization": "", "Orders": [], "Patient": { "First Name": "", "Last Name": "", "Birth Date": "", "Gender": "", "Phone": "", "Email": "", "Address": "" } }, "section_header": "", "section_date": "", "section_note_id": 0, "section_note_type": "" } ``` #### Important Notes {% hint style="info" %} Mimetype of the response will always be JSON even if CDA is requested. {% endhint %} ## 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.
DescriptionUpload the documents you want to use to generate a medical summary or include with the documents you retrieved from /search-patient in Step 2
MethodPOST
Routehttps://api.abstractive.ai/upload-patient-docs
Success Status Code200 or 202
Avg. Response Time (Success)180 - 300 seconds
#### Input Parameters ## POST /upload-patient-docs > 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 ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/upload-patient-docs":{"post":{"tags":["upload-patient-docs"],"description":"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","responses":{"200":{"description":"Documents successfully uploaded and processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsSuccess"}}}},"202":{"description":"Documents uploaded and processing started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsSuccess"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsAuthenticationFailure"}}}},"404":{"description":"Patient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsNotFoundFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsRequest"}}}}}}},"components":{"schemas":{"UploadPatientDocsSuccess":{"description":"Successful document upload","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200,202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID"},"document_count":{"type":"integer","description":"Number of files successfully processed"},"processing":{"type":"boolean","description":"Whether processing is occurring"}}},"UploadPatientDocsValidationFailure":{"description":"Upload patient docs validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["ValidationError"]},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}}}},"UploadPatientDocsAuthenticationFailure":{"description":"Upload patient docs authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["AuthenticationError"]}}},"UploadPatientDocsNotFoundFailure":{"description":"Upload patient docs not found failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[404]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["NotFoundError"]}}},"UploadPatientDocsInternalServerError":{"description":"Upload patient docs internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["InternalServerError"]}}},"UploadPatientDocsRequest":{"description":"Upload Patient Documents Input - supports two modes (existing patient or new patient with metadata)","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"conversation_id":{"type":"string","description":"Optional conversation ID. If not provided, one will be generated"},"patient_id":{"type":"string","description":"Existing patient ID (for Option 1)"},"patient_metadata":{"type":"object","description":"Patient metadata (for Option 2 - new patients)","properties":{"addresses":{"type":"array","description":"List of patient addresses","items":{"type":"object","properties":{"street_address_line":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"2-letter capitalized state code"},"postal_code":{"type":"string","description":"5-digit postal code"},"country":{"type":"string","description":"3-letter capitalized country code"}}}},"demographics":{"type":"object","description":"Patient demographic details","properties":{"given_name":{"type":"string","description":"Patient's given name"},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient's gender code (M or F)"},"birth_time":{"type":"string","description":"Patient's birth date in YYYYMMDD format"},"phone_number":{"type":"string","description":"Patient's phone number in nnn-nnn-nnnn format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}},"files":{"type":"object","description":"Base64 encoded files organized by type","properties":{"non_text":{"type":"array","items":{"type":"string","description":"Base64 encoded PDF files"}},"cda":{"type":"array","items":{"type":"string","description":"Base64 encoded CDA files"}},"fhir":{"type":"array","items":{"type":"string","description":"Base64 encoded FHIR files"}}}}},"required":["user_api_email","token","files"]}}}} ``` {% hint style="info" %} 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. {% endhint %} ## 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.
DescriptionGenerate 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.
MethodPOST
Routehttps://api.abstractive.ai/request-summary
Success Status Code202
Avg. Response Time (Success)3 - 5 seconds
#### Input Parameters ## POST /request-summary > Requests a summary of an entire conversation containing patient documents ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/request-summary":{"post":{"tags":["request-summary"],"description":"Requests a summary of an entire conversation containing patient documents","responses":{"202":{"description":"Processing started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryProcessing"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryRequest"}}}}}}},"components":{"schemas":{"RequestSummaryProcessing":{"description":"Processing status for summary request","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[true]}}},"RequestSummaryFailure":{"description":"Failed summary request","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error"},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"missing_fields":{"type":"array","description":"missing required fields (if validation error)","items":{"type":"string"}}}},"RequestSummaryRequest":{"description":"Input object to request a conversation summary","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"patient_id":{"type":"string","description":"Unique patient identifier"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","patient_id","conversation_id"]}}}} ``` #### Important Notes {% hint style="info" %} Limit summary requests to 1 every 30 seconds. {% endhint %} ## Step 5. Retrieve a Summary
DescriptionRetrieve the summary after requesting to create one through /request-summary API endpoint
MethodPOST
Routehttps://api.abstractive.ai/retrieve-summary
Success Status Code200
Avg. Response Time (Success)60 - 180 seconds
#### Input Parameters ## POST /retrieve-summary > Retrieves a completed conversation summary ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/retrieve-summary":{"post":{"tags":["retrieve-summary"],"description":"Retrieves a completed conversation summary","responses":{"200":{"description":"Summary ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummarySuccess"}}}},"202":{"description":"Summary still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryProcessing"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"404":{"description":"Conversation_id not recognized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryRequest"}}}}}}},"components":{"schemas":{"RetrieveSummarySuccess":{"description":"Successful summary retrieval response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL to download summary"},"expires_in":{"type":"integer","description":"URL expiration time in seconds","enum":[3600]},"posted":{"type":"boolean","description":"Whether URL is posted","enum":[true]},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[false]}}},"RetrieveSummaryProcessing":{"description":"Processing status for summary retrieval","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["processing"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"message":{"type":"string","description":"Description of processing status"},"posted":{"type":"boolean","description":"Whether URL is posted","enum":[false]},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[true]}}},"RetrieveSummaryFailure":{"description":"Failed summary retrieval response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error"},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"missing_fields":{"type":"array","description":"missing required fields (if validation error)","items":{"type":"string"}},"posted":{"type":"boolean","description":"whether url is posted","enum":[false]}}},"RetrieveSummaryRequest":{"description":"Input object to retrieve a generated conversation summary","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","conversation_id","patient_id"]}}}} ``` #### **Format of cleaned\_text\_notes/** ``` { "section_content": { "Document Title": "", "Document Date": "", "Encounter Type": "", "Reason for Visit": "", "Allergies": [], "Immunizations": [], "Medications": [], "Vitals": [], "Labs": [], "Images": [], "Procedures": [], "Location": "", "Location Type": "", "Medical History": [], "Social History": "", "Family History": [], "Document Text": [], "Providers": [""], "Organization": "", "Orders": [], "Patient": { "First Name": "", "Last Name": "", "Birth Date": "", "Gender": "", "Phone": "", "Email": "", "Address": "" } }, "section_header": "", "section_date": "", "section_note_id": 0, "section_note_type": "" } ``` #### 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: ```json { "conversation_id": "", "section_summaries": [ { "section_header": "", "section_summary": { "Events": "", "Followups": [], "Providers": [], "Medication": [] } } ], "section_entities": [ { "section_page":0, "section_header": "", "section_entities":[{ "Text": "", "Type": "", "Score": 0.0, "Traits":[], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }] } ], "meta_summary":{ "HPI": "", "Labs": [], "Images": [], "Vitals": [], "Allergies": [], "FamilyHistory": "", "SocialHistory": "", "PastClinicalEvents": [], "AllHistoricalFollowups": [], "AllHistoricalProviders": [], "AllHistoricalMedications": [] }, "meta_entities": { "HPI": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "Labs": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "Images": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "Vitals": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "Allergies": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "FamilyHistory": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "SocialHistory": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "PastClinicalEvents": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "AllHistoricalFollowups": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "AllHistoricalProviders": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], "AllHistoricalMedications": [{ "Text": "", "Type": "", "Score": 0.0, "Traits": [], "Category": "", "Codemaps": {}, "Endoffset": 0, "Beginoffset": 0, "Attributes": [] }], }, "patient_metadata": { "dob": "", "sex": "", "address": "", "last_name": "", "first_name": "", "phone_number": "", "provider_name": "" }, "scoring": { "SimilarityScores":{ "HPI": { "OverallScore": 0.0, "Sentences": {} }, "Labs": { "OverallScore": 0.0, "Sentences": {} }, "Images": { "OverallScore": 0.0, "Sentences": {} }, "Vitals": { "OverallScore": 0.0, "Sentences": {} }, "Allergies": { "OverallScore": 0.0, "Sentences": {} }, "FamilyHistory": { "OverallScore": 0.0, "Sentences": {} }, "SocialHistory": { "OverallScore": 0.0, "Sentences": {} }, "PastClinicalEvents": { "OverallScore": 0.0, "Sentences": {} }, "AllHistoricalFollowups": { "OverallScore": 0.0, "Sentences": {} }, "AllHistoricalProviders": { "OverallScore": 0.0, "Sentences": {} }, "AllHistoricalMedications": { "OverallScore": 0.0, "Sentences": {} } } } } ``` #### 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 | {% hint style="info" %} Scores can exceed 1.0 when the lexical overlap bonus is added to a high cosine similarity. This is expected behavior. {% endhint %} #### Important Notes {% hint style="info" %} * You can retrieve a summary every 15 seconds. * We recommend not retrieving the same summary more than 30 times {% endhint %} ## 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 NameDescription
DescriptionSend a new clinical treatment document to Abstractive Health
MethodPOST
Routehttps://api.abstractive.ai/push-document
Avg. Response Time (Success)10 - 15 seconds
## POST /push-document > Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/push-document":{"post":{"tags":["push-document"],"description":"Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata","responses":{"200":{"description":"All pushed documents completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentSuccess"}}}},"207":{"description":"Some pushed documents completed successfully while others failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentPartialSuccess"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentAuthenticationFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentRequest"}}}}}}},"components":{"schemas":{"PushDocumentSuccess":{"description":"All pushed documents completed successfully","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer","enum":[200]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"message":{"type":"string","description":"Combined message across pushed note results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PushDocumentResult"}}}},"PushDocumentResult":{"description":"Result for a single pushed note","type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"status_code":{"type":"integer","description":"HTTP-style status code for this item"},"processing":{"type":"boolean","description":"Whether this pushed note is still processing"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the result was generated"},"patient_id":{"type":"string","description":"Patient identifier associated with the pushed note"},"document_count":{"type":"integer","description":"Number of documents created for this item"},"note_id":{"type":"string","description":"Unique identifier for the pushed note"},"summary_id":{"type":"string","description":"Summary identifier associated with the pushed note"},"message":{"type":"string","description":"Result message"},"failure_reason":{"type":"string","description":"Failure reason for failed items when available"},"error":{"type":"string","description":"Failure detail for failed items when available"}}},"PushDocumentPartialSuccess":{"description":"Some pushed documents completed successfully while others failed","type":"object","properties":{"status":{"type":"string","enum":["partial_success"]},"status_code":{"type":"integer","enum":[207]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"message":{"type":"string","description":"Combined message across pushed note results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PushDocumentResult"}}}},"PushDocumentValidationFailure":{"description":"Push document validation failure","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[400]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"invalid_fields":{"type":"object","additionalProperties":{"type":"string"}}}},"PushDocumentAuthenticationFailure":{"description":"Push document authentication failure","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[401]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"}}},"PushDocumentInternalServerError":{"description":"Push document internal server error","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[500]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"},"error_details":{"type":"string"}}},"PushDocumentRequest":{"description":"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.","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false},"author":{"$ref":"#/components/schemas/PushDocumentAuthor"},"summaries":{"type":"array","description":"One or more summaries to push as structured notes","items":{"$ref":"#/components/schemas/PushDocumentSummary"},"minItems":1}},"required":["user_api_email","token","author","summaries"]},"PushDocumentAuthor":{"description":"Provider metadata attached to the pushed note","type":"object","properties":{"given_name":{"type":"string","description":"First name of the authoring clinician"},"family_name":{"type":"string","description":"Last name of the authoring clinician"},"authored_on":{"type":"string","description":"Date the treatment summary was authored. The public documentation expects YYYYMMDD format."},"npi":{"type":"string","description":"10-digit National Provider Identifier of the authoring clinician. Do not pass an organization NPI.","pattern":"^\\d{10}$"},"specialty":{"type":"string","description":"Medical specialty of the authoring clinician"}},"required":["given_name","family_name","authored_on","npi","specialty"]},"PushDocumentSummary":{"description":"Summary payload for a single pushed note","type":"object","properties":{"summary_id":{"type":"string","description":"Existing summary identifier to associate with the pushed note"},"patient_id":{"type":"string","description":"Existing patient identifier generated by Abstractive Health during patient search or summarization. If provided, other patient demographic fields are optional."},"patient_metadata":{"allOf":[{"$ref":"#/components/schemas/PatientSearchMetadata"}],"description":"Patient demographics and optional addresses used to resolve or create a patient when patient_id is not supplied."},"summary_assessment":{"type":"string","description":"Plain-text narrative describing the clinical context or assessment reflected by the summary, such as diagnoses, treatment rationale, visit purpose, or key findings."},"summary_edited":{"type":"string","description":"Final version of the medical summary after any manual edits. This becomes the official treatment note pushed into the exchange. Required when summary_id is not supplied."},"summary_format":{"type":"string","description":"Format of summary_edited. Use json when submitting an edited structured summary payload previously returned by Abstractive Health.","enum":["text","json"],"default":"text"}},"required":["summary_assessment"]},"PatientSearchMetadata":{"description":"Patient metadata used for patient search. Demographics are required. Addresses are optional but materially improve matching quality.","type":"object","properties":{"addresses":{"type":"array","description":"List of patient addresses. If provided, each item must include all address fields below.","items":{"$ref":"#/components/schemas/PatientSearchAddress"}},"demographics":{"$ref":"#/components/schemas/PatientSearchDemographics"}},"required":["demographics"]},"PatientSearchAddress":{"description":"Patient address used for patient matching. Include places where the patient has lived throughout their life when available.","type":"object","properties":{"street_address_line":{"type":"string","description":"Street address where the patient lived or currently lives"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State or province code, typically a two-letter U.S. abbreviation such as NY"},"postal_code":{"type":"string","description":"Postal or ZIP code"},"country":{"type":"string","description":"Country code for the address. Current records are limited to the United States."}},"required":["street_address_line","city","state","postal_code","country"]},"PatientSearchDemographics":{"description":"Patient demographic details","type":"object","properties":{"given_name":{"type":"string","description":"Patient's given name. Include middle names here when available."},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient gender code","enum":["M","F"]},"birth_time":{"type":"string","description":"Patient birth date in YYYYMMDD format","pattern":"^\\d{8}$"},"email":{"type":"string","description":"Patient's email address"},"phone_number":{"type":"string","description":"Patient phone number, typically in XXX-XXX-XXXX format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}}} ``` #### Important Notes {% hint style="info" %} * You are required to return a clinical treatment document for every patient retrieved from Carequality® within 7 days. {% endhint %} ## 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
DescriptionAsk a clinical question about a patient's chart. Returns an AI-generated answer with source references from the patient's documents.
MethodPOST
Routehttps://api.abstractive.ai/ask
Success Status Code200
Avg. Response Time (Success)5 - 15 seconds
## POST /ask > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/ask":{"post":{"tags":["question-answering"],"description":"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.\n","responses":{"200":{"description":"Answer generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}}}}},"components":{"schemas":{"AskResponse":{"description":"Successful answer to a clinical question","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"answer":{"type":"string","description":"AI-generated clinical answer grounded in the patient's chart"},"conversation_id":{"type":"string","description":"Conversation identifier. Pass this in subsequent /ask calls to continue the conversation, or in /get-alert-event follow-ups.\n"},"message_id":{"type":"string","description":"Unique identifier for this specific message"},"sources":{"type":"array","description":"Clinical chart excerpts used to generate the answer","items":{"$ref":"#/components/schemas/SourceChunk"}}}},"SourceChunk":{"description":"A clinical note excerpt used as evidence for an answer","type":"object","properties":{"content":{"type":"string","description":"Excerpt text from the clinical note"},"note_title":{"type":"string","description":"Title or type of the source document"},"timestamp":{"type":"string","description":"Date/time the source note was created"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"AskRequest":{"description":"Request to ask a clinical question about a patient","type":"object","required":["user_api_email","token","patient_id","question"],"properties":{"user_api_email":{"type":"string","description":"API user email address"},"token":{"type":"string","description":"API access token obtained from POST /get-token"},"patient_id":{"type":"string","description":"Internal patient identifier returned by POST /search-patient"},"question":{"type":"string","description":"Natural-language clinical question about the patient"},"conversation_id":{"type":"string","description":"Conversation ID from a previous /ask response. Pass this to continue an existing conversation rather than starting a new one.\n"}}}}}} ``` #### Important Notes {% hint style="info" %} * 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. {% endhint %} ### List Conversations
DescriptionList all question & answer conversations for the authenticated user, optionally filtered by patient.
MethodGET or POST
Routehttps://api.abstractive.ai/list-conversations
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /list-conversations > List Q\&A conversations for the authenticated user, optionally filtered by patient. ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/list-conversations":{"post":{"tags":["question-answering"],"description":"List Q&A conversations for the authenticated user, optionally filtered by patient.","responses":{"200":{"description":"Conversations retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConversationsRequest"}}}}}}},"components":{"schemas":{"ConversationListResponse":{"description":"List of Q&A conversations","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}}}},"ConversationSummary":{"description":"Summary of a Q&A conversation","type":"object","properties":{"conversation_id":{"type":"string"},"title":{"type":"string","description":"Auto-generated title based on the first question"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of the last message"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"ListConversationsRequest":{"description":"Request to list Q&A conversations","type":"object","required":["user_api_email","token"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"patient_id":{"type":"string","description":"Optional — filter conversations to a specific patient"}}}}}} ``` ### Get Conversation
DescriptionRetrieve the full message history of a specific conversation by its ID.
MethodGET or POST
Routehttps://api.abstractive.ai/get-conversation
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /get-conversation > Retrieve the full message history of a Q\&A conversation. ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/get-conversation":{"post":{"tags":["question-answering"],"description":"Retrieve the full message history of a Q&A conversation.","responses":{"200":{"description":"Conversation retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetConversationRequest"}}}}}}},"components":{"schemas":{"ConversationResponse":{"description":"Full message history of a Q&A conversation","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"conversation_id":{"type":"string"},"title":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}}}},"ConversationMessage":{"description":"A single message in a Q&A conversation","type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","description":"Message text"},"created_at":{"type":"string","description":"ISO 8601 timestamp"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"GetConversationRequest":{"description":"Request to retrieve a full conversation","type":"object","required":["user_api_email","token","conversation_id"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"conversation_id":{"type":"string"}}}}}} ``` ## 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
DescriptionCreate a new care notification for your organisation. It will run automatically on every new patient summary.
MethodPOST
Routehttps://api.abstractive.ai/create-alert
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /create-alert > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/create-alert":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Care notification created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertCreatedResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlertRequest"}}}}}}},"components":{"schemas":{"AlertCreatedResponse":{"description":"Care notification created","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"alert_id":{"type":"string","description":"Unique identifier for the newly created care notification"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"CreateAlertRequest":{"description":"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.\n","type":"object","required":["user_api_email","token","title","question_text","answer_type","trigger_type"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"title":{"type":"string","description":"Short display name for the care notification (max 30 characters)"},"question_text":{"type":"string","description":"The clinical question asked of the patient's chart by the AI. Write it as a specific, answerable question.\n"},"answer_type":{"type":"string","description":"Expected answer format — numeric measurement or boolean yes/no","enum":["number","boolean"]},"trigger_type":{"type":"string","description":"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`.\n","enum":["number_above","number_below","number_between","boolean_true","boolean_false"]},"threshold_low":{"type":"number","description":"Lower threshold. Required for `number_above` and `number_between`. Notification fires when the extracted value exceeds this.\n"},"threshold_high":{"type":"number","description":"Upper threshold. Required for `number_between`."},"value_unit":{"type":"string","description":"Unit of measurement for the extracted value"},"include_guidelines":{"type":"boolean","description":"When true, the AI also searches PubMed and clinical guidelines for additional context in the response.\n","default":false}}}}}} ``` ### Edit a Care Notification
DescriptionUpdate an existing care notification. A new version is created automatically; prior versions are archived.
MethodPOST
Routehttps://api.abstractive.ai/edit-alert
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /edit-alert > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/edit-alert":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Care notification updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEditedResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditAlertRequest"}}}}}}},"components":{"schemas":{"AlertEditedResponse":{"description":"Care notification updated","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"alert_id":{"type":"string"},"version_id":{"type":"string","description":"ID of the newly created version"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"EditAlertRequest":{"description":"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`.\n","type":"object","required":["user_api_email","token","alert_id"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"alert_id":{"type":"string","description":"The care notification to update"},"title":{"type":"string"},"question_text":{"type":"string"},"answer_type":{"type":"string","enum":["number","boolean"]},"trigger_type":{"type":"string","enum":["number_above","number_below","number_between","boolean_true","boolean_false"]},"threshold_low":{"type":"number"},"threshold_high":{"type":"number"},"value_unit":{"type":"string"},"include_guidelines":{"type":"boolean"}}}}}} ``` #### Important Notes {% hint style="info" %} * 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. {% endhint %} ### List Care Notifications
DescriptionList all active care notifications for your organisation.
MethodGET or POST
Routehttps://api.abstractive.ai/list-alerts
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /list-alerts > List all care notifications configured for this organisation. ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/list-alerts":{"post":{"tags":["care-notifications"],"description":"List all care notifications configured for this organisation.","responses":{"200":{"description":"Care notifications retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthOnlyRequest"}}}}}}},"components":{"schemas":{"AlertListResponse":{"description":"List of care notifications for the organisation","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/AlertDefinition"}}}},"AlertDefinition":{"description":"A care notification","type":"object","properties":{"alert_id":{"type":"string"},"version_id":{"type":"string","description":"Active version identifier"},"title":{"type":"string"},"answer_type":{"type":"string","enum":["number","boolean"]},"trigger_type":{"type":"string"},"threshold_low":{"type":"number"},"threshold_high":{"type":"number"},"value_unit":{"type":"string"},"enabled":{"type":"boolean","description":"Whether this care notification is active for your account"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"AuthOnlyRequest":{"description":"Request that requires authentication only — no additional parameters","type":"object","required":["user_api_email","token"],"properties":{"user_api_email":{"type":"string","description":"API user email address"},"token":{"type":"string","description":"API access token obtained from POST /get-token"}}}}}} ``` ### List Notification Results
DescriptionRetrieve 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.
MethodGET or POST
Routehttps://api.abstractive.ai/list-alert-events
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /list-alert-events > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/list-alert-events":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Notification results retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEventListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAlertEventsRequest"}}}}}}},"components":{"schemas":{"AlertEventListResponse":{"description":"Most recent care notification result per notification for a patient","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"events":{"type":"array","items":{"$ref":"#/components/schemas/AlertEventSummary"}}}},"AlertEventSummary":{"description":"Summary of a single care notification result","type":"object","properties":{"event_id":{"type":"string","description":"Unique identifier for this notification result"},"alert_id":{"type":"string"},"title":{"type":"string","description":"Care notification title"},"triggered":{"type":"boolean","description":"Whether the patient meets the trigger criteria for this care notification"},"pending":{"type":"boolean","description":"True while the AI is still evaluating; poll until false"},"fired_at":{"type":"string","description":"ISO 8601 timestamp of when the care notification was evaluated"},"conversation_id":{"type":"string","description":"Conversation ID linked to this result. Pass to POST /ask to ask follow-up questions in this context.\n"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"ListAlertEventsRequest":{"description":"Request to list care notification results for a patient","type":"object","required":["user_api_email","token","patient_id"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"patient_id":{"type":"string","description":"The patient to retrieve notification results for"},"created_after":{"type":"string","description":"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.\n"},"alert_id":{"type":"string","description":"Filter to results for a specific care notification"},"triggered":{"type":"boolean","description":"Filter to only triggered (true) or non-triggered (false) results"},"limit":{"type":"integer","description":"Maximum number of results to return (default 50, max 200)"},"offset":{"type":"integer","description":"Pagination offset"}}}}}} ``` ### Get Notification Result
DescriptionRetrieve the full details of a single care notification result, including the AI-generated clinical response and supporting chart evidence.
MethodGET or POST
Routehttps://api.abstractive.ai/get-alert-event
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /get-alert-event > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/get-alert-event":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Notification result retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEventDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"404":{"description":"Result not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAlertEventRequest"}}}}}}},"components":{"schemas":{"AlertEventDetailResponse":{"description":"Full detail of a care notification result","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer"},"processing":{"type":"boolean","description":"True if the evaluation is still in progress"},"event_id":{"type":"string"},"alert_id":{"type":"string"},"title":{"type":"string"},"triggered":{"type":"boolean","description":"Whether the patient meets the trigger criteria for this care notification"},"trigger_value":{"description":"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.\n"},"value_unit":{"type":"string","description":"Unit for numeric trigger values"},"response":{"type":"string","description":"AI-generated clinical narrative summarising the finding"},"conversation_id":{"type":"string","description":"Continue the conversation with POST /ask using this ID to ask follow-up questions about this care notification finding.\n"},"sources":{"type":"array","description":"Chart evidence the AI drew on when answering the notification question","items":{"$ref":"#/components/schemas/SourceChunk"}},"fired_at":{"type":"string","description":"ISO 8601 timestamp of the evaluation"}}},"SourceChunk":{"description":"A clinical note excerpt used as evidence for an answer","type":"object","properties":{"content":{"type":"string","description":"Excerpt text from the clinical note"},"note_title":{"type":"string","description":"Title or type of the source document"},"timestamp":{"type":"string","description":"Date/time the source note was created"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"GetAlertEventRequest":{"description":"Request to retrieve a specific care notification result","type":"object","required":["user_api_email","token","event_id"],"properties":{"user_api_email":{"type":"string"},"token":{"type":"string"},"event_id":{"type":"string","description":"The event ID from a /list-alert-events response"}}}}}} ``` #### Important Notes {% hint style="info" %} * Use the `conversation_id` from this response with `POST /ask` to ask follow-up questions about the care notification finding. {% endhint %} ### Delete a Care Notification
DescriptionPermanently 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.
MethodPOST
Routehttps://api.abstractive.ai/delete-alert
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /delete-alert > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/delete-alert":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Care notification archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAlertResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"403":{"description":"Forbidden — caller is not the owner of this notification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"404":{"description":"Care notification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAlertRequest"}}}}}}},"components":{"schemas":{"DeleteAlertResponse":{"description":"Confirmation that the care notification has been archived","properties":{"status":{"type":"string"},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"archived":{"type":"boolean","description":"Always true on success"},"already_archived":{"type":"boolean","description":"Present and true if the notification was already archived before this call"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"DeleteAlertRequest":{"description":"Input object to archive a care notification","required":["user_api_email","token","alert_id"],"properties":{"user_api_email":{"type":"string","description":"Your API user email address"},"token":{"type":"string","description":"Your API authentication token"},"alert_id":{"type":"string","description":"UUID of the care notification to archive"}}}}}} ``` #### Important Notes {% hint style="info" %} * 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. {% endhint %} ### Run Care Notifications
DescriptionManually 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.
MethodPOST
Routehttps://api.abstractive.ai/run-alerts
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /run-alerts > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/run-alerts":{"post":{"tags":["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 — 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.\n","responses":{"200":{"description":"Alert jobs dispatched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAlertsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAlertsRequest"}}}}}}},"components":{"schemas":{"RunAlertsResponse":{"description":"Confirmation that care notification jobs have been dispatched","properties":{"status":{"type":"string"},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"dispatched":{"type":"integer","description":"Total number of individual alert evaluation jobs fired (patients × notifications)"},"total_patients":{"type":"integer","description":"Total matching patients found before the 50-patient cap was applied"},"truncated":{"type":"boolean","description":"True if the patient count exceeded 50 and only the first 50 were processed. Call again to process the remaining patients.\n"},"dispatched_at":{"type":"string","description":"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.\n"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"RunAlertsRequest":{"description":"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.\n","required":["user_api_email","token"],"properties":{"user_api_email":{"type":"string","description":"Your API user email address"},"token":{"type":"string","description":"Your API authentication token"},"patient_id":{"type":"string","description":"Run all active notifications for a single patient"},"team_api_code":{"type":"string","description":"Run all active notifications for every patient on this team. Use the team's human-readable api_code (not the UUID team_id).\n"},"run_for_org":{"type":"boolean","description":"Run all active notifications for every patient in the organisation. Capped at 50 patients per call — check the truncated field.\n"}}}}}} ``` #### Important Notes {% hint style="info" %} * 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. {% endhint %} ### Set Webhook (Callback URL)
DescriptionConfigure a callback URL for your organisation. When set, a POST request is sent to this URL automatically each time a care notification evaluation completes.
MethodPOST
Routehttps://api.abstractive.ai/set-webhook
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /set-webhook > 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.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/set-webhook":{"post":{"tags":["care-notifications"],"description":"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.\n","responses":{"200":{"description":"Webhook URL updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetWebhookResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetWebhookRequest"}}}}}}},"components":{"schemas":{"SetWebhookResponse":{"description":"Confirmation of the webhook URL update","properties":{"status":{"type":"string"},"status_code":{"type":"integer"},"webhook_url":{"type":"string","description":"The webhook URL that was stored, or null if removed"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"SetWebhookRequest":{"description":"Input object to set or clear the care notification callback webhook URL","required":["user_api_email","token"],"properties":{"user_api_email":{"type":"string","description":"Your API user email address"},"token":{"type":"string","description":"Your API authentication token"},"webhook_url":{"type":"string","description":"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.\n"}}}}}} ``` ### Get Webhook (Callback URL)
DescriptionRetrieve the care notification webhook URL currently configured for your organisation.
MethodGET or POST
Routehttps://api.abstractive.ai/get-webhook
Success Status Code200
Avg. Response Time (Success)~1 second
## POST /get-webhook > Retrieve the care notification webhook URL currently configured for your organisation. Returns null if no webhook has been set.
```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/get-webhook":{"post":{"tags":["care-notifications"],"description":"Retrieve the care notification webhook URL currently configured for your organisation. Returns null if no webhook has been set.\n","responses":{"200":{"description":"Webhook URL retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWebhookResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWebhookRequest"}}}}}}},"components":{"schemas":{"GetWebhookResponse":{"description":"The currently configured care notification webhook URL for the organisation","properties":{"status":{"type":"string"},"status_code":{"type":"integer"},"processing":{"type":"boolean"},"webhook_url":{"type":"string","description":"The configured webhook URL, or null if none has been set"}}},"GenericFailure":{"description":"Generic error response returned for 4xx/5xx errors","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer"},"failure_reason":{"type":"string","description":"Human-readable explanation of the error"},"missing_fields":{"type":"array","items":{"type":"string"},"description":"Fields absent from the request (validation errors only)"},"processing":{"type":"boolean"}}},"GetWebhookRequest":{"description":"Input object to retrieve the configured webhook URL","required":["user_api_email","token"],"properties":{"user_api_email":{"type":"string","description":"Your API user email address"},"token":{"type":"string","description":"Your API authentication token"}}}}}} ``` #### Webhook Payload When a care notification evaluation completes, Abstractive POSTs the following JSON to your callback URL: ```json { "event_id": "uuid", "alert_id": "uuid", "patient_id": "uuid", "patient_name": "Jane Smith", "patient_dob": "01/15/1980", "patient_gender": "F", "conversation_id": "uuid", "triggered": true, "trigger_value_num": 8.2, "trigger_value_bool": null, "value_unit": "%", "value_observed_at": "2024-02-10", "question_text": "What is the patient's most recent HbA1c?", "response": "The patient's most recent HbA1c was 8.2% recorded on 2024-02-10..." } ``` #### Important Notes {% hint style="info" %} * 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. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://resources.abstractivehealth.com/api-documentation/reference-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.