API reference

API Reference

Resources, endpoints, and payloads. All requests are JSON over HTTPS and authenticated with a bearer token.

Contacts

The core resource — a living profile with history, health, and commitments.

GET/v1/contacts

GET/v1/contacts/{id}

POST/v1/contacts

PATCH/v1/contacts/{id}

json

{
  "id": "ctc_amara_okafor",
  "name": "Amara Okafor",
  "title": "Managing Partner",
  "company": "Kestrel Capital",
  "location": "London, UK",
  "health": "warm",
  "tags": ["investor", "climate"],
  "last_touch": "2026-07-11T09:30:00Z",
  "commitments": [
    { "owner": "you", "body": "Send revised deck", "due": "2026-07-15", "status": "open" }
  ],
  "sources": [
    { "kind": "voice", "label": "Voice reflection · 11 Jul" }
  ]
}

Capture

Create a contact from a scanned card, signature, or vCard. The write is immediate; enrichment and outreach remain consent-gated.

POST/v1/capture

json

// request
{ "name": "Yuki Mori", "company": "Aozora Ventures", "email": "y.mori@aozora.vc", "source": "business_card" }

// response
{ "id": "ctc_yuki_mori", "status": "indexed", "enrichment": "pending_review" }

Assistant

Ask the chief-of-staff in natural language. Answers cite sources; any action is returned as a draft you must confirm separately.

POST/v1/assistant/ask

json

// request
{ "message": "What do I owe Amara, and draft the follow-up?" }

// response
{
  "text": "You owe Amara the revised deck + 2027 model, due in 2 days…",
  "sources": [{ "kind": "commitment", "ref": "cmt_123" }],
  "draft": { "id": "drf_abc", "type": "email", "requires_confirmation": true }
}

Nothing is sent until you confirm the draft:

POST/v1/drafts/{id}/confirm

Groups

GET/v1/groups

GET/v1/groups/{id}

POST/v1/groups

Errors & rate limits

The API uses conventional HTTP status codes: 2xx success, 4xx for client errors (bad request, auth, not found), 5xx for server errors. Errors return a JSON body:

json

{ "error": { "type": "invalid_request", "message": "A name is required." } }

Rate limits are applied per workspace. When exceeded, the API returns 429 with a Retry-After header. Handle it with exponential backoff.