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

# REST API

> Traditional HTTP API for Arlo Health integration

## Overview

Arlo Health exposes two interfaces backed by the same handlers and authentication: **MCP** (the primary interface for AI agents, at `/`) and this **REST API** (at `/api/*`) for bots, skills, and direct HTTP clients.

## Base URL

```
https://mcp.arlohealth.ai
```

All REST endpoints are prefixed with `/api/`.

## Authentication

Arlo uses OAuth 2.1 with PKCE for authentication. All REST endpoints (except discovery) require a valid Bearer token.

### Discovery Endpoints

| Endpoint                                  | Description                                  |
| ----------------------------------------- | -------------------------------------------- |
| `/.well-known/mcp.json`                   | MCP Server Card for capability discovery     |
| `/.well-known/oauth-protected-resource`   | OAuth protected resource metadata (RFC 9728) |
| `/.well-known/oauth-authorization-server` | OAuth authorization server metadata          |

### OAuth Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Arlo
    participant Auth

    Client->>Arlo: GET /.well-known/oauth-authorization-server
    Arlo-->>Client: Authorization server metadata

    Client->>Auth: Authorization request (PKCE)
    Auth-->>Client: Authorization code

    Client->>Arlo: Token exchange
    Arlo-->>Client: Access token + refresh token

    Client->>Arlo: API request with Bearer token
    Arlo-->>Client: Response
```

### Making Authenticated Requests

Include your access token in the `Authorization` header:

```bash theme={null}
curl -X GET https://mcp.arlohealth.ai/api/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Available Endpoints

### Consultations

| Method | Endpoint                                    | Description                                                      |
| ------ | ------------------------------------------- | ---------------------------------------------------------------- |
| GET    | `/api/consultations`                        | List the user's conversations                                    |
| POST   | `/api/consultations`                        | Start a new conversation (requires `contextMessage` + `region`)  |
| GET    | `/api/consultations/{id}`                   | Get conversation status and messages                             |
| PATCH  | `/api/consultations/{id}/region`            | Update the region a conversation is licensed for                 |
| DELETE | `/api/consultations/{id}`                   | Stop the current provider request (conversation returns to IDLE) |
| POST   | `/api/consultations/{id}/messages`          | Send a message (supports `lastSeenMessageId` + `waitForReply`)   |
| POST   | `/api/consultations/{id}/confirm`           | Confirm provider connection (places the per-visit hold)          |
| GET    | `/api/consultations/{id}/notes`             | Get provider visit notes                                         |
| POST   | `/api/consultations/{id}/media`             | Get upload URL for media                                         |
| GET    | `/api/consultations/{id}/media/{messageId}` | Get media download URL                                           |

### Profile

| Method | Endpoint                    | Description                                           |
| ------ | --------------------------- | ----------------------------------------------------- |
| GET    | `/api/profile`              | Get user profile                                      |
| PATCH  | `/api/profile/patient`      | Update patient information                            |
| POST   | `/api/profile/accept-terms` | Record ToS/Privacy acceptance and complete onboarding |

### Payments

Arlo is pay-per-use. (Endpoint paths retain the `subscription` name for compatibility.)

| Method | Endpoint                     | Description                                                        |
| ------ | ---------------------------- | ------------------------------------------------------------------ |
| GET    | `/api/subscription`          | Get payment status and pay-per-use options                         |
| POST   | `/api/subscription/setup`    | Create a Stripe card-setup session (saves a card; does not charge) |
| POST   | `/api/subscription/activate` | Deprecated — recovery path for a stuck PENDING payment             |
| DELETE | `/api/subscription`          | Deprecated — legacy subscription cancellation                      |

### Prescriptions

| Method | Endpoint                           | Description                                                                                                                           |
| ------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/prescriptions`               | List prescriptions                                                                                                                    |
| GET    | `/api/prescriptions/{id}`          | Get prescription details                                                                                                              |
| POST   | `/api/prescriptions/{id}/pharmacy` | Select pharmacy (legacy `ARLO` fax flow only — US orders are managed by Photon Health and refuse selection with `MANAGED_EXTERNALLY`) |
| GET    | `/api/pharmacies`                  | Search for pharmacies                                                                                                                 |

### Webhooks

| Method | Endpoint       | Description                |
| ------ | -------------- | -------------------------- |
| GET    | `/api/webhook` | Get webhook status         |
| POST   | `/api/webhook` | Register or update webhook |

## Quick Start Example

Here's a complete example of starting a conversation:

```bash theme={null}
# 1. Start a conversation (region = where the patient is right now)
curl -X POST https://mcp.arlohealth.ai/api/consultations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contextMessage": "I have had a sore throat for 3 days and it hurts to swallow. No fever but I feel tired.",
    "region": "US-CA"
  }'

# Response (fast-ack — triage replies arrive asynchronously):
# {
#   "conversationId": "abc123",
#   "status": "TRIAGING"
# }

# 2. Send a follow-up message
curl -X POST https://mcp.arlohealth.ai/api/consultations/abc123/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "No white patches, but my throat is red and swollen.",
    "waitForReply": true
  }'

# 3. Check conversation status
curl -X GET https://mcp.arlohealth.ai/api/consultations/abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "error": "error_code",
  "reason": "Human-readable explanation",
  "needsAuth": false
}
```

### Common Error Codes

| Code                   | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| `not_authenticated`    | User needs to sign up or sign in                             |
| `REGION_NOT_SUPPORTED` | Patient's current region is not supported                    |
| `READ_REQUIRED`        | Send refused — fetch the latest conversation state and retry |
| `payment_hold_failed`  | Card declined or insufficient funds                          |
| `no_payment_gate`      | Conversation not in PAYMENT\_REQUIRED status                 |
| `MANAGED_EXTERNALLY`   | US prescription — fulfillment is handled by Photon Health    |

## Rate Limits

API requests are rate-limited to ensure service quality. Contact support if you need higher limits.

## Support

* Website: [arlohealth.ai](https://www.arlohealth.ai)
* Contact: [keaton@arlohealth.ai](mailto:keaton@arlohealth.ai)