> ## Documentation Index
> Fetch the complete documentation index at: https://aftercaredocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Medications from a Recovery Plan — GET /medications

> Retrieve medications from a recovery plan with GET /medications. Record doses taken with POST /medications/{id}/taken. Both require authentication.

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

<ParamField query="documentId" type="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.
</ParamField>

### Response — 200 OK

Returns an object with a `data` array of `Medication` objects.

```json theme={null}
{
  "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]
    }
  ]
}
```

<ResponseField name="data" type="Medication[]">
  Array of extracted medication objects.

  <Expandable title="Medication object">
    <ResponseField name="id" type="string">
      Unique identifier for this medication record. Use this value in `POST /medications/{medicationId}/taken`.
    </ResponseField>

    <ResponseField name="name" type="string">
      The medication name as it appears in the discharge document, e.g. `"Metformin"`.
    </ResponseField>

    <ResponseField name="dose" type="string">
      The prescribed dose, e.g. `"500 mg"` or `"10 mg/5 mL"`.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      How often the medication should be taken, e.g. `"twice daily"` or `"every 8 hours"`.
    </ResponseField>

    <ResponseField name="timing" type="string">
      When relative to meals or other activities the medication should be taken, e.g. `"with meals"` or `"at bedtime"`.
    </ResponseField>

    <ResponseField name="instructions" type="string">
      Any additional administration instructions extracted from the document.
    </ResponseField>

    <ResponseField name="takenAt" type="string[]">
      ISO 8601 timestamps for each recorded dose, appended by `POST /medications/{medicationId}/taken`. Empty array if no doses have been recorded yet.
    </ResponseField>

    <ResponseField name="confidence" type="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.
    </ResponseField>

    <ResponseField name="sourceLines" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  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.
</Note>

### cURL example

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

***

## POST /medications/{medicationId}/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

<ParamField path="medicationId" type="string" required>
  The `id` of the medication to mark as taken. Must belong to the authenticated user.
</ParamField>

### Response — 201 Created

Returns the adherence event that was recorded.

```json theme={null}
{
  "medicationId": "med_01J4KXYZ",
  "takenAt": "2024-09-14T14:30:00.000Z"
}
```

### cURL example

```bash theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.