REST API

API keys are minted from Settings → API keys inside the cockpit. The full secret is shown once at creation — store it securely. We only retain the SHA-256 hash for validation.

Every request must include the key as a Bearer token. The key itself encodes the organization it belongs to — no extra tenant header needed.

curl https://api.adaptlive.app/api/v1/schema \
  -H "Authorization: Bearer ak_live_ABCDEFGHJKMNPQRSTVWXYZ0123456789"

The wire format is ak_<env>_<32-char-base32> — ak_live_ for production, ak_test_ for sandbox. The secret is 160 bits of Crockford base32 entropy.

Keys carry a scope — READ, WRITE, or ADMIN — with a strict hierarchy: ADMIN ⊇ WRITE ⊇ READ. Pick the smallest scope that lets the integration do its job. Revoke any key from the same settings screen — it stops authenticating immediately.

Every approved partner gets two orgs side-by-side: a sandbox seeded with realistic-but-fake data (keys prefixed ak_test_) and the production org tied to real numbers, real customers, and real outbound SMS (keys prefixed ak_live_).

The two surfaces are byte-identical — same endpoints, same payloads, same webhook envelope — so an integration tested against sandbox runs unchanged in production once the operator swaps the key.

To get keys: apply at /work-with-us → on approval you land in /portal with both orgs already provisioned.

List recent work records (filter by kind):

curl "https://api.adaptlive.app/api/v1/work-records?kind=JOB&limit=25" \
  -H "Authorization: Bearer ak_test_ABCDEFGHJKMNPQRSTVWXYZ0123456789"

Send an outbound SMS (with idempotency):

curl -X POST https://api.adaptlive.app/api/v1/sms \
  -H "Authorization: Bearer ak_test_..." \
  -H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "body": "Confirming your 3pm appointment tomorrow."
  }'

Subscribe to webhook events:

curl -X POST https://api.adaptlive.app/api/v1/webhooks \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":       "Production callback",
    "url":        "https://example.com/hooks/adaptlive",
    "eventTypes": ["call.ended", "sms.received", "draft.approved"]
  }'

Confirm a proposed fact:

curl -X POST https://api.adaptlive.app/api/v1/facts/ckxxx.../confirm \
  -H "Authorization: Bearer ak_live_..."

Send an Idempotency-Key header on any POST or PATCH. We store the response for 24 hours and replay it verbatim when the same key arrives again — safe to retry through proxies, load balancers, or job runners.

If you reuse the same key with a different request body, we return 422 Unprocessable Entity with code: "idempotency_conflict". Use a fresh key per logical operation.

POST /api/v1/work-records
Authorization: Bearer ak_live_...
Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-1a2b3c4d5e6f
Content-Type: application/json

{
  "kind":     "JOB",
  "personId": "ckxxxxxxxx",
  "title":    "Emergency water leak"
}

Every list endpoint is cursor-paginated. Pass ?limit= (1–100, default 25) and the ?cursor=value returned in the previous page's envelope. Cursors are opaque base64 — do not parse them, just round-trip what we hand you.

{
  "data": [ /* ... */ ],
  "page": {
    "nextCursor": "eyJpZCI6ImNreHh4eHh4eHgifQ==",
    "hasMore":    true
  },
  "requestId": "req_01HYZ..."
}

Order is stable: rows are ordered by createdAt desc with id as the tiebreaker, so paging never skips or duplicates a row even when many records share a millisecond.

Token-bucket per organization, refilled per second:

• Read endpoints — 100 req/sec sustained, 200 burst
• Write endpoints — 30 req/sec sustained, 60 burst

When you hit the limit we return 429 Too Many Requests with Retry-After in seconds. Back off respectfully and retry — token capacity refills continuously.

Subscribe via the POST /api/v1/webhooks endpoint or from Settings → Webhooks. Each subscription gets a signing secret (shown once at creation). We POST a signed JSON envelope to your URL when matching events fire. Delivery is at-least-once — dedupe on eventId.

Headers we send on every delivery:

Content-Type: application/json
X-AdaptLive-Signature: t=1717009200,v1=<hmac-sha256-hex>
X-AdaptLive-Event: call.ended
X-AdaptLive-Event-Id: 01HYZ...

Verify the signature by reconstructing <t>.<rawBody> and comparing your own HMAC-SHA256 to the v1 value, constant-time. Reject deliveries where the t timestamp is older than 5 minutes.

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header, body, secret) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  return timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(v1, "hex"),
  );
}

Event types we currently emit:

Replays + dead letters: deliveries failing all retries land in DEAD_LETTERED and can be re-queued individually via POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay.

Retries: 8 attempts with exponential backoff (30s → 24h). After max attempts we dead-letter the delivery; you can re-queue from the audit log or via the replay endpoint above.

If you want webhook + REST automation without writing code, the AdaptLive Zapier app exposes 16 triggers, 5 actions, and 2 searches against this same v1 surface. It uses real-time REST hook subscriptions (via POST /api/v1/webhooks) and falls back to polling for sample loads.

Source + trigger catalog: apps/zapier/README.md.