List Medications from a Recovery Plan — GET /medications

Once AfterCare finishes processing a document, use the medications endpoints to retrieve the structured medication list and to record when a patient takes a dose. The GET /medications endpoint returns every medication AfterCare extracted from the discharge paperwork, including dosage, frequency, and administration instructions. The POST /medications/{medicationId}/taken endpoint writes an adherence event so you can track compliance over time.

GET /medications

Retrieve all medications associated with a processed document.

Query parameter

string (UUID)

required

The document identifier returned by POST /upload. The response only includes medications that belong to this document and are owned by the authenticated user.

Response — 200 OK

Returns an object with a data array of Medication objects.

{
  "data": [
    {
      "id": "med_01J4KXYZ",
      "name": "Metformin",
      "dose": "500 mg",
      "frequency": "twice daily",
      "timing": "with meals",
      "instructions": "Take with food to reduce stomach upset. Do not skip doses.",
      "takenAt": ["2024-09-14T08:00:00.000Z"],
      "confidence": 94,
      "sourceLines": [42, 43, 44]
    }
  ]
}

Medication[]

Array of extracted medication objects.

Show Medication object

string

Unique identifier for this medication record. Use this value in POST /medications/{medicationId}/taken.

string

The medication name as it appears in the discharge document, e.g. "Metformin".

string

The prescribed dose, e.g. "500 mg" or "10 mg/5 mL".

string

How often the medication should be taken, e.g. "twice daily" or "every 8 hours".

string

When relative to meals or other activities the medication should be taken, e.g. "with meals" or "at bedtime".

string

Any additional administration instructions extracted from the document.

string[]

ISO 8601 timestamps for each recorded dose, appended by POST /medications/{medicationId}/taken. Empty array if no doses have been recorded yet.

number

AfterCare’s extraction confidence for this medication, expressed as an integer from 0 to 100. A score of 100 means AfterCare is highly confident the information is accurate. A low score (for example, below 70) means the text was ambiguous — always cross-reference those items against the original discharge document before presenting them to the patient.

number[]

The line numbers in the original uploaded document where this medication was found. Use these to show the patient exactly where in their paperwork a medication came from — for example, to highlight the relevant passage when a confidence score is low.

AfterCare assigns a confidence score to every extracted medication. Low-confidence items are still returned so you have the full picture, but you should prompt the patient to check their original paperwork for any medication with a score below your acceptable threshold.

cURL example

curl -G https://api.aftercare.app/medications \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  --data-urlencode "documentId=550e8400-e29b-41d4-a716-446655440000"

POST /medications//taken

Record that a patient took a dose of a specific medication. AfterCare appends the current server timestamp to the medication’s takenAt array.

Path parameter

string

required

The id of the medication to mark as taken. Must belong to the authenticated user.

Response — 201 Created

Returns the adherence event that was recorded.

{
  "medicationId": "med_01J4KXYZ",
  "takenAt": "2024-09-14T14:30:00.000Z"
}

cURL example

curl -X POST https://api.aftercare.app/medications/med_01J4KXYZ/taken \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Error responses

Status	Endpoint	Meaning
`401`	Both	Missing or invalid Bearer token.
`404`	`GET /medications`	No recovery plan found for the given `documentId`, or the document does not belong to the authenticated user.
`404`	`POST /medications/{id}/taken`	Medication not found, or it does not belong to the authenticated user.

Overview

Endpoints

List Medications from a Recovery Plan — GET /medications

GET /medications

Query parameter

Response — 200 OK

cURL example

POST /medications//taken

Path parameter

Response — 201 Created

cURL example

Error responses

​GET /medications

​Query parameter

​Response — 200 OK

​cURL example

​POST /medications//taken

​Path parameter

​Response — 201 Created

​cURL example

​Error responses

GET /medications

Query parameter

Response — 200 OK

cURL example

POST /medications//taken

Path parameter

Response — 201 Created

cURL example

Error responses