Cairn API (0.1.0)

ATH-250 — cursor-paginated over ULID id descending (newest first). The cursor is an opaque id; paginating on a non-nullable, monotonic, unique column is what keeps a page boundary stable while rows are being written underneath it, which a timestamp cursor cannot promise.

ATH-250 — upsert semantics on email, which is the workspace's unique key for a contact. An integration replaying its backlog must not create duplicates, and asking every caller to GET before POST would make that a race rather than a guarantee; a repeat POST therefore updates and returns 200, a first POST creates and returns 201. Blank incoming values never clobber stored ones, matching the CSV import's rule. Subject to the plan's contact ceiling (422 when full).

ATH-250 — a contact in another workspace is 404, never 403: a 403 would confirm the id exists somewhere, which is a cross-tenant disclosure however small.

ATH-250 — partial update; omitted fields are left alone. email is not updatable here: it is the dedupe key, so changing it would silently merge or split identities. Re-POST to /contacts to upsert against a different email.

ATH-250 — cursor-paginated over ULID id descending, same contract as /contacts. Read-only in v1: REPLYING through the public API sends a message to a real customer under the workspace's name, and that deserves its own ticket with the channel-window rules (WhatsApp's 24h, ATH-180) and the suppression list wired in, rather than being smuggled in behind a parity checkbox here.

ATH-250 — the conversation plus its messages, oldest first. Internal notes (direction=note) are EXCLUDED: they are staff commentary written in the belief that the customer will never see them, and an integration token is not staff. Another workspace's id is 404, never 403.

ATH-253 — the deliverable event catalog, derived at runtime from the events that implement PubliclyDeliverable (ATH-251). An integration builder renders this as the event picker, so a name that is not here cannot be subscribed to and a name that is here is guaranteed to be able to arrive.

ATH-253 — cursor-paginated, newest first. An iPaaS platform needs this to RECONCILE: a Zap deleted while Cairn was unreachable leaves an endpoint nobody will ever unsubscribe, and without a list call the only way to find it is the portal. The signing secret is never included — it is returned exactly once, by the create call.

ATH-253 — the subscribe half of a REST hook. Creates an ATH-251 endpoint and its subscriptions in one call and returns the HMAC signing secret EXACTLY ONCE, in this response body. A trigger implementation is expected to keep that secret with the subscription and verify Cairn-Signature on every delivery; there is no reveal endpoint, because "show me the secret again" and "rotate the secret" are the same operation from a security standpoint and only one of them leaves the existing verifier working.

url is validated by ATH-202's DNS-free SSRF guard here and by the resolving guard on every delivery attempt.

ATH-253 — the unsubscribe half of a REST hook. Subscriptions, deliveries and attempts cascade. Another workspace's id is 404, never 403.

ATH-258 — vector + FTS retrieval fused by RRF (the ATH-154 engine) for non-MCP consumers and the Cairn MCP server. Requires a workspace API key with the retrieval:query ability; the key names the tenant, so results can never cross workspaces. Audience governance (Doc 07 §5): keys see public + customers chunks; internal chunks require the retrieval:internal ability and are silently excluded otherwise — requesting an audience the key may not see narrows to the permitted set (fail closed), it never errors content into view.

ATH-258 — the document read behind a guide:{id} hit, for MCP cairn_get_guide. Requires a workspace API key with the guides:read ability. Published guides only, and only those whose share-mode audience the key may see (private guides map to internal and need retrieval:internal); anything else is 404 — existence is never confirmed across the audience fence.

ATH-258 — the document read behind an article:{id} hit, for MCP cairn_get_article. Requires a workspace API key with the articles:read ability. Published articles only, and only those whose access-level audience the key may see (internal access needs retrieval:internal); anything else is 404 — existence is never confirmed across the audience fence.

No session: the credential in the request (widget key, invitation token, or webhook signature) names the tenant and is verified server-side.

When the session is an impersonation (ATH-034), impersonation is present — clients MUST render the banner from it.

ATH-252 — the ONLY path in this spec that carries no ability and no bearer token, because it is what mints them. It authenticates the CLIENT (client_id + client_secret) and, for the authorization-code grant, the PKCE code_verifier. An Cairn API key presented here is ignored and the request still fails: this endpoint answers nothing to a credential it did not issue.

PKCE is MANDATORY, not negotiable. code_challenge_method must be S256 at the authorize step and a matching code_verifier must arrive here; there is no plain method and no path that skips the check, so a downgrade attempt is a 400 rather than a weaker flow.

An authorization code is SINGLE USE and short-lived. Replaying a consumed code fails AND revokes the access token that code already issued, because a replay means the code leaked and the first exchange may not have been the legitimate one.

Refresh tokens ROTATE: every refresh returns a new refresh token and consumes the presented one. Presenting an already-consumed refresh token is treated as theft and revokes the app's entire token family for that workspace — the standard OAuth 2.1 / RFC 6819 §5.2.2.3 response, and the reason rotation is worth having at all.

Errors follow RFC 6749 §5.2 (error + error_description) rather than the house error.code envelope. That is a deliberate exception: every off-the-shelf OAuth client library parses this shape, and an authorization server that invents its own error format is one that integrators have to hand-write a client for.

ATH-253 — Zapier and n8n both need a "is this connection still good?" call they can make on a schedule. ATH-250 deferred a GET /v1/token for that, because an ability-free endpoint that answers 2xx to a bearer token is precisely what its route-enumeration invariant exists to forbid, and excluding one would have made the exclusion list the real boundary.

This endpoint is not that. It is RFC 7662 introspection, and the RFC's own design is what resolves the tension: the caller authenticates as the CLIENT (client_id + client_secret) and passes the token it is asking about as a PARAMETER. A bearer token is not a credential here, exactly as at /oauth/token. So this route is swept by PublicApiSurfaceTest like every other api/v1 route, answers 401 to the live wildcard API key the sweep fires at it, and needs no exclusion and no ability. The invariant is untouched because nothing ability-free was added to it.

Per RFC 7662 §2.2 an inactive, expired, revoked or unknown token is {"active": false} with status 200 — NOT an error. A client must branch on active, never on the status code. Nothing beyond active is returned in that case, so this endpoint cannot be used to probe which token strings exist.

Scoping: a client may only introspect a token it was itself issued. Asking about another app's token answers {"active": false} — the same answer as a token that does not exist, because distinguishing the two would turn this into an oracle for other apps' credentials.

ATH-252 — requires integrations.manage. These are the apps the workspace OWNS and publishes, not the apps installed into it (that is /oauth-installs). The client secret existed once, in the create response, and is not recoverable from here or from anywhere else.

ATH-252 — requires integrations.manage. redirect_uris are matched EXACTLY at authorize time: no prefix matching, no wildcards, no trailing-slash forgiveness. A near miss is a refusal, because prefix matching on a redirect URI is how an open redirect turns into a stolen authorization code.

requested_abilities is the app's CEILING, drawn from the ATH-250 vocabulary (ApiAbilities::all()); unknown abilities are rejected 422 at registration rather than silently granting nothing later. No consent may exceed this set, and no consent may exceed the granting user's own permissions either.

ATH-252 — requires integrations.manage, and only the OWNING workspace may call it. Withdrawing an app revokes every install of it in every workspace and every token those installs hold, immediately: a developer shutting down an integration should not leave live credentials pointed at their customers.

ATH-252 — requires integrations.manage. The other side of /oauth-apps: what this workspace has granted to somebody else's app, in the ability vocabulary the consent screen used, so "what can this integration actually do" has an answer that does not require reading code.

ATH-252 — requires integrations.manage. Sets revoked_at on the install AND on every access token it issued, so access ends immediately rather than at the next token expiry. The rows are kept rather than deleted for the same reason a revoked API key's row is kept: last_used_at is what an incident review reads.

Idempotent — revoking an already-revoked install returns the same 200 with the original timestamp, because the caller's intent is already satisfied and a 409 would only encourage retry loops in the one situation where speed matters.

Authenticated (session or API key); any member of the workspace may call it.

ATH-018 — authenticated; the caller becomes the new workspace's owner. Pre-context (no workspace to authorize against yet). Idempotency-Key replays the same workspace for 24h.

ATH-018 — any member of the workspace; membership is enforced by workspace.context before the handler runs.

ATH-018 — requires settings.manage. settings MERGES rather than replaces, so a partial update never clobbers keys it did not send.

PA-270 — that merge is DEEP, at every level. Objects are merged key by key: {"voice":{"recording_enabled":false}} changes that one key and leaves voice.recording_announcement and voice.greeting exactly as they were. (Until PA-270 it merged only the top level, so the same request deleted the rest of the voice object silently.)

ARRAYS ARE REPLACED WHOLESALE, never merged element by element — that is what lets a list SHRINK. Send the list you want stored; send [] to empty it.

AN EMPTY OBJECT NAMES NO KEYS, so {"voice":{}} changes nothing under voice (and {"settings":{}} changes nothing at all).