REST API - Arlo Health

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

Making Authenticated Requests

Include your access token in the Authorization header:

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:

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

{
  "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
Contact: keaton@arlohealth.ai

​Overview

​Base URL

​Authentication

​Discovery Endpoints

​OAuth Flow

​Making Authenticated Requests

​Available Endpoints

​Consultations

​Profile

​Payments

​Prescriptions

​Webhooks

​Quick Start Example

​Error Responses

​Common Error Codes

​Rate Limits

​Support