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.

The price-transparency endpoints are a separate, anonymous surface at https://api.arlohealth.ai/api/pricing.v1. No token is needed there. See the Pricing API tab.

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}/payment`	Stripe Checkout link where the patient approves the hold for one visit
GET	`/api/consultations/{id}/notes`	Get provider visit notes
POST	`/api/consultations/{id}/media`	Send a photo or video (base64 `data` or public `url`), or get a presigned upload URL
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/complete-onboarding`	Complete onboarding once the required fields are saved

Payments

Arlo is pay-per-use: each visit is approved on a Stripe page via POST /api/consultations/{id}/payment.

Method	Endpoint	Description
GET	`/api/payment`	Per-visit price and payment state (informational)

Prescriptions

Method	Endpoint	Description
GET	`/api/prescriptions`	List prescriptions
GET	`/api/prescriptions/{id}`	Get prescription details
POST	`/api/prescriptions/{id}/pharmacy`	Select the pharmacy for an `ARLO`-fulfilled order. Orders managed by Photon Health 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

MCP-only capabilities

Health records (get_health_records, start_flexpa_link, complete_flexpa_import), care requests (create_care_request and companions), and the resumable wait_for_reply are MCP tools without REST equivalents here. Care pricing has its own anonymous Pricing API.

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
`no_payment_gate`	Conversation not in PAYMENT_REQUIRED status
`summary_loading`	The payment gate is still being set up; retry shortly
`unsupported_country` / `invalid_state`	Patient update with a non-US country or a state code that is not a US state
`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

​MCP-only capabilities

​Quick Start Example

​Error Responses

​Common Error Codes

​Rate Limits

​Support

Overview

Base URL

Authentication

Discovery Endpoints

OAuth Flow

Making Authenticated Requests

Available Endpoints

Consultations

Profile

Payments

Prescriptions

Webhooks

MCP-only capabilities

Quick Start Example

Error Responses

Common Error Codes

Rate Limits

Support