Skip to content
For developers
View as Markdown

Integration cheat sheet

Everything an agent needs to start calling ActuallyCare, in one page: base URL, auth, one working request, and the MCP connect URL.

The minimum viable context for integrating with ActuallyCare. Everything here is expanded elsewhere — this page is sized for an agent's context window.

REST API#

  • Base URL: https://api.actuallycare.com/v1
  • Auth: send your API key in the X-API-Key header. Create one under Settings → API Keys in the web app (or POST /v1/api-keys with a JWT) and grant it scopes — a key with no scopes gets 403 on everything. JWT bearer auth also works: POST /v1/auth/login → Authorization: Bearer <token>. Four endpoint groups are JWT-only (API keys get 401): /api-keys, /webhooks, /contacts, /billing.
  • First request:
curl -s https://api.actuallycare.com/v1/escrows \
  -H "X-API-Key: $ACTUALLYCARE_API_KEY"
  • Envelope: every response is { "success": true|false, "data": ..., "error": { "code", "message" } }. Branch on error.code, never the message.
  • Pagination: ?page=1&limit=50 on list endpoints; the response meta carries totals. Details: Pagination.
  • Spec: openapi.json · Errors · Rate limits

MCP server#

  • Endpoint: https://mcp.actuallycare.com/mcp (Streamable HTTP)
  • Auth: OAuth 2.1 with PKCE and dynamic client registration — clients discover everything from the 401 WWW-Authenticate header. An ActuallyCare login is required at the consent screen.
  • Connect from Claude: Settings → Connectors → Add custom connector → paste the endpoint URL. Walkthrough: Connect Claude in 5 minutes.
  • Tool index: tools.json — names, descriptions, input schemas, safety annotations for every tool.

Webhooks#

Register via POST /v1/webhooks (JWT bearer auth, broker or system-admin role); deliveries are HMAC-signed. Setup and verification: Set up webhooks.

Machine-readable docs#

llms.txt · llms-full.txt · append .md to any page URL · .well-known/ai.json