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.

PA-394 — server-side contact event ingestion: record what only your back end knows (first_order_placed, plan_upgraded) so segments (event_count, event_window) and experience rules (event_window) can match on it. Up to 100 events per call. Name each contact by contact_id, external_id or email — the most specific one given wins — and contacts are never created here: upsert them with POST /contacts first.

A malformed batch — over 100 events, a name outside ^[a-z][a-z0-9_.:-]{0,63}$ (or starting cairn./cairn:), properties beyond 20 flat scalar keys / 500-character strings / 4 KB, no contact identifier, an occurred_at older than 30 days or in the future — is 422 and writes nothing. A well-formed event naming a contact this workspace does not have is reported by its index in rejected (contact_not_found) and the rest are written; another workspace's contact is indistinguishable from an unknown one. Retry with the same Idempotency-Key to get the first answer back without writing twice. Behind feature.api.public_v1 and feature.contacts.event_tracking (404 below either).

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.

Doc 12 §4.4 R16(b) (E2-6) — cursor-paginated over ULID id descending, same contract as /contacts. Filter by type and status. Identity and status only: the draft, its steps and its rules are authoring data and stay on the workspace API.

Doc 12 §4.4 R16(b) (E2-6) — the same summary shape as the list. Another workspace's id is 404, never 403.

Doc 12 §4.4 R16(b) (E2-6, E2-9) — the rows the portal's per-person table reads (ExperienceProgressRow), newest first, cursor-paginated. Sessioned types (tour, program, survey) emit one row per session; session-less types (launcher, banner, announcement) emit one row per experience_seen marker — session_id is the marker id, version_id is null. Filter by state and contact_id.

Doc 12 §4.4 R16(b) (E2-6) — every experience this contact has a ledger row for: a session (tours, programs, surveys) or a seen marker (launchers, banners, announcements), collapsed to ONE state per experience with the same precedence the rules engine uses (active > completed > dismissed > seen). Experiences the contact has never met are not listed — "unseen" is the absence of a row. Another workspace's contact is 404.

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.

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-250 — requires api_keys.manage. Returns metadata only: the plaintext key existed once, in the create response, and is not recoverable from anywhere including here. key_prefix is what lets a human match a row to the key in their password manager. Revoked keys are included, because "which keys did we kill and when" is the question this list is most often opened to answer.

Requires api_keys.manage. Scoped to the workspace in the path — a member of another workspace gets 403, never another tenant’s rows.

ATH-250 — requires api_keys.manage. Sets revoked_at; the row is kept rather than deleted so an incident review can still read last_used_at and answer "was it used before we killed it". Idempotent: revoking an already-revoked key returns the same 200 with the original timestamp, because the caller's intent ("this key must not work") is already satisfied and a 409 would only encourage retry loops during the one situation where speed matters.

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.

PA-394 — server-side contact event ingestion: record what only your back end knows (first_order_placed, plan_upgraded) so segments (event_count, event_window) and experience rules (event_window) can match on it. Up to 100 events per call. Name each contact by contact_id, external_id or email — the most specific one given wins — and contacts are never created here: upsert them with POST /contacts first.

A malformed batch — over 100 events, a name outside ^[a-z][a-z0-9_.:-]{0,63}$ (or starting cairn./cairn:), properties beyond 20 flat scalar keys / 500-character strings / 4 KB, no contact identifier, an occurred_at older than 30 days or in the future — is 422 and writes nothing. A well-formed event naming a contact this workspace does not have is reported by its index in rejected (contact_not_found) and the rest are written; another workspace's contact is indistinguishable from an unknown one. Retry with the same Idempotency-Key to get the first answer back without writing twice. Behind feature.api.public_v1 and feature.contacts.event_tracking (404 below either).

ATH-096 — the customer's app signs visitor JWTs (HS256, exp required) with this per-workspace secret; the help center verifies them to unlock 'authenticated' articles. Readable by settings managers only. sign_in_url (design v2 S79) is where the private help centre's "Sign in" sends a reader, and return_url where the customer's app sends them back.

Design v2 S79. "Sign in" sends the reader to sign_in_url with return_to added: the PATH on the help centre they wanted (/ when none), never an address. The customer's app signs them in, mints the visitor JWT and redirects to return_url — a fixed address it knows, never one taken from the request — adding token=<jwt> and return=<return_to>; the help centre lands them on that path. So a token only ever goes to the help centre, whatever a link carries. An https page of the customer's own (http only for a loopback host while developing), with no return_to of its own, and never a Cairn host. Needs the signing secret: a sign-in page without one answers 422, because no reader could come back signed in. null removes it, and the page goes back to saying where to sign in from. Audited. Behind feature.helpcenter.sign_in_url (404 when off).

ATH-096 — rotation invalidates every outstanding visitor JWT signed with the old secret immediately.