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.
Last updated
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-Keyheader. Create one under Settings → API Keys in the web app (orPOST /v1/api-keyswith a JWT) and pick its scopes —read,writeanddeleteare separate grants, and a request outside them gets403. JWT bearer auth also works:POST /v1/auth/login→Authorization: Bearer <token>. These endpoints are JWT-only (API keys get401): the/authsession and profile endpoints,/api-keys,/webhooks, and authenticated/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 onerror.code, never the message. - Pagination:
?page=1&limit=50on most list endpoints; the responsemetacarries totals./v1/contactsignorespage— useoffsetthere. 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-Authenticateheader. An ActuallyCare login is required at the consent screen. Custom clients can also send an API key inX-API-Keyor a JWT as a bearer token. - Tool surface:
tools/listadvertises a set of everyday tools. Claude's apps can call only those; a custom client can call any catalog tool by name. - Connect from Claude: Customize → Connectors → + Add → Add custom connector → paste the endpoint URL → Continue → Add. 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