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

# AfterCare REST API Overview and Base URL

> A complete reference for the AfterCare REST API: base URL, Bearer token auth, JSON content types, rate limiting, and structured error format.

The AfterCare REST API lets you upload hospital discharge paperwork, stream processing progress, and retrieve structured recovery data — including medications, appointments, and document-grounded answers. Every endpoint is served under the `/api` path on the same origin as the web app and returns JSON unless otherwise noted.

## Base URL

All requests go to the AfterCare web app origin:

```
https://aftercare-web-eta.vercel.app/api
```

Include this base URL as the prefix for every endpoint path shown in this reference.

## Authentication

Most endpoints require a valid JWT access token supplied as a Bearer token in the `Authorization` header. The exceptions are `GET /health`, the `/auth/*` routes, and `GET /drive/callback`, which are all public.

```http theme={null}
Authorization: Bearer <accessToken>
```

See [Authentication](/api/authentication) for the full register → login → token refresh flow.

## Content Types

Most requests and all standard responses use JSON. Two endpoints return non-JSON bodies:

| Endpoint | Response type |
| - | - |
| `GET /process/{documentId}` | `text/event-stream` (Server-Sent Events) |
| `POST /appointments/{appointmentId}/calendar` | `text/calendar` (ICS file download) |

Send `Content-Type: application/json` for all JSON request bodies. For file uploads, send `Content-Type: multipart/form-data`.

## Rate Limiting

The API enforces per-user request budgets on a rolling one-hour window. Once you are authenticated, limits are tracked against your user ID rather than your IP address. Three separate limit tiers apply:

* **General API requests** — applied to most endpoints
* **Upload requests** — a stricter budget for `POST /upload`
* **Ask requests** — the tightest budget for `POST /ask`, which triggers live AI inference

When you exceed a limit, the API responds with `429 Too Many Requests` and a JSON body:

```json theme={null}
{
  "error": "API rate limit exceeded. Try again later.",
  "code": "RATE_LIMITED"
}
```

Rate limit state is communicated through standard `RateLimit-*` response headers. Check these headers to track your remaining quota and reset time before you hit the ceiling.

<Tip>
  Space out document uploads and `/ask` calls in bulk workflows. The upload and ask budgets reset on a rolling one-hour window, so distributing requests evenly avoids unexpected 429 responses.
</Tip>

## Health Check

Use `GET /health` to verify that the API is reachable and that AI provider configuration is present. This endpoint requires no authentication.

```http theme={null}
GET /api/health
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://aftercare-web-eta.vercel.app/api/health
  ```

  ```js fetch theme={null}
  const res = await fetch("https://aftercare-web-eta.vercel.app/api/health");
  console.log(res.status); // 200
  ```
</CodeGroup>

A `200` response confirms the service is healthy.

## Error Format

Standard errors (invalid input, missing resources, authentication failures) follow ordinary HTTP status codes and return a plain JSON body with an `error` string and an optional `code`.

AI pipeline errors from `POST /ask` and `GET /process/{documentId}` return a richer structured format:

```json theme={null}
{
  "code": "AI_PROVIDER_OUTAGE",
  "message": "The AI provider is temporarily unavailable.",
  "retryable": true
}
```

<ResponseField name="code" type="string" required>
  Machine-readable error code. One of the values in the table below.
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable explanation of the error, safe to display to end users.
</ResponseField>

<ResponseField name="retryable" type="boolean" required>
  When `true`, the same request may succeed if you try again after a short delay. When `false`, the request will continue to fail until the underlying issue is resolved (for example, missing provider configuration).
</ResponseField>

### AI Error Codes

| Code | HTTP status | Retryable | Meaning |
| - | - | - | - |
| `AI_PROVIDER_CONFIG_MISSING` | `503` | No | AI integration is not configured in this environment. |
| `AI_PROVIDER_OUTAGE` | `503` | Yes | The AI provider is experiencing a temporary outage. |
| `AI_PROVIDER_UNAVAILABLE` | `503` | Yes | The AI provider is unreachable or capacity-limited. |
| `AI_VALIDATION_FAILED` | `422` | No | The request was rejected by a safety validation layer. |

<Warning>
  Only `AI_VALIDATION_FAILED` uses a `422` status code. All other AI errors return `503`. Check `retryable` before deciding whether to surface a retry option to your users.
</Warning>

## Explore the API

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Register, log in, refresh tokens, and sign out.
  </Card>

  <Card title="Upload" icon="arrow-up-from-bracket" href="/api/upload">
    Upload discharge paperwork and start AI processing.
  </Card>

  <Card title="Medications" icon="pills" href="/api/medications">
    Retrieve medication schedules and record doses taken.
  </Card>

  <Card title="Appointments" icon="calendar" href="/api/appointments">
    List upcoming follow-up appointments and download calendar events.
  </Card>
</CardGroup>


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