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. A drop-in integration guide for agent runtimes is served at https://mcp.arlohealth.ai/skill.md.

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.

Care pricing is served here with the user’s token at /api/pricing/*, with the plan resolved from their linked insurance. The same lookups are also available anonymously at https://api.arlohealth.ai/api/pricing.v1; 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
DELETE	`/api/consultations/{id}`	Stop the current provider request (conversation returns to IDLE)
POST	`/api/consultations/{id}/messages`	Send a message (supports `lastSeenMessageId` + `waitForReply`)
GET	`/api/consultations/{id}/reply`	Block until the next reply lands (the resumable wait); `afterMessageId`, `maxWaitSeconds`
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

Visit Payments

Each visit is approved on the Stripe page linked from the conversation’s paymentGate.paymentUrl. The patient approves a temporary hold there; it is charged only if a doctor joins and is released otherwise. There is no card setup step.

Method	Endpoint	Description
GET	`/api/payment`	Per-visit price

Prescriptions

Method	Endpoint	Description
GET	`/api/prescriptions`	List prescriptions
GET	`/api/prescriptions/{id}`	Get prescription details

Webhooks

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

Health Records (US insurance)

Method	Endpoint	Description
GET	`/api/health-records`	Connected insurance and health records; `section=summary` (default) for counts, then `coverage`, `conditions`, `medications`, `allergies`, `immunizations`, `labs`, `vitals`, `visits`, `claims`, or `everything`
POST	`/api/health-records/link`	Start a records connection; returns `authorizationUrl` (15 minutes), `linkNonce`, and the `notice` to relay first
GET	`/api/health-records/link/{linkNonce}`	Poll the connection: `pending`, `imported`, `cancelled`, `failed`, or `expired`

Care Pricing (free, US)

The plan resolves from the user’s linked insurance; planHints sharpen it when the response asks. Request and response fields match the Pricing API.

Method	Endpoint	Description
POST	`/api/pricing/search`	Nearby in-network options with estimated rates for a catalog `code`
POST	`/api/pricing/network-status`	Whether a named provider or facility is in-network, and their contracted rate with a `code`. Call first for any named clinic
POST	`/api/pricing/provider-evidence`	Public-data evidence about one provider by `npi`

Care Jobs (US)

Method	Endpoint	Description
POST	`/api/care-jobs`	Propose `move_referral`, `book_appointment`, `cancel_or_reschedule`, `send_records`, `dispute_claim`, or `resolve_billing_issue`; returns `approvalUrl` for the user. Send `Idempotency-Key` on retries
GET	`/api/care-jobs`	The account’s care jobs, those waiting on the user first
GET	`/api/care-jobs/{id}`	Status, audit trail, and the care team’s open questions (`openItems`)
POST	`/api/care-jobs/{id}/answers`	Answer the care team’s open questions
GET	`/api/care-jobs/{id}/wait`	Resumable wait until the job changes

The MCP and REST interfaces share handlers for overlapping operations. The route table above lists the HTTP operations in this REST contract.

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
`unsupported_country` / `invalid_state`	Patient update with a non-US country or a state code that is not a US state

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

​Visit Payments

​Prescriptions

​Webhooks

​Health Records (US insurance)

​Care Pricing (free, US)

​Care Jobs (US)

​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

Visit Payments

Prescriptions

Webhooks

Health Records (US insurance)

Care Pricing (free, US)

Care Jobs (US)

Quick Start Example

Error Responses

Common Error Codes

Rate Limits

Support