HTTP overview

Learn Checkfu’s base URL, wire format, identifiers, pagination, and streaming conventions.

The Checkfu interface is JSON over HTTPS, with Server-Sent Events for replay-then-live Session streams.

Checkfu is in private alpha. Get access and identities covers where a key comes from if you do not have one yet.

Base URL

https://api.checkfu.com/v1

Every versioned request requires a Workspace-bound API key and a supported dated wire version.

Authorization: Bearer <api-key>
Checkfu-Version: 2026-08-27
Content-Type: application/json

The Workspace comes from the API key. Selector headers are rejected; see Authentication and versions.

Mutating POST requests also accept Idempotency-Key. Use a unique, stable value for each intended mutation so a network retry resolves to the original mutation instead of creating another Session or driving another turn. Most routes replay the first response; erasure-safe routes retain only opaque IDs and rehydrate current live authority, so deletion returns 404 and a mutable resource may reflect a later status. API-key creation and rotation require this header because their one-time secrets cannot be regenerated after a committed write.

Identifiers

Resources use typed, prefixed IDs with 32 lowercase hexadecimal characters after the prefix. The prefix is part of the type: an endpoint expecting a sess_ will reject an agent_ rather than looking it up.

The ones you meet first:

Resource	Example
Workspace	wrkspc_0123456789abcdef0123456789abcdef
Agent	agent_0123456789abcdef0123456789abcdef
Principal	prin_0123456789abcdef0123456789abcdef
Session	sess_0123456789abcdef0123456789abcdef
Run	run_0123456789abcdef0123456789abcdef
Event	evt_0123456789abcdef0123456789abcdef
ActionApproval	approval_0123456789abcdef0123456789abcdef
Connection	conn_0123456789abcdef0123456789abcdef
MemoryStore	memstore_0123456789abcdef0123456789abcdef

Every resource carries a prefix in this shape. The API reference section names the exact prefix each endpoint expects in its request and response shapes.

Pagination

List responses use cursor pagination:

{
  "data": [],
  "next_page": null
}

Pass a non-null next_page value back in the next request’s page query parameter. Cursors are opaque unless an endpoint explicitly says otherwise.

Where a list endpoint accepts order=asc|desc, it defaults to asc, and desc walks newest-first. The cursor does not encode direction, so resend order on every page; a follow-up that omits it silently reads ascending from that position.

Three read paths use a different cursor. Transcript discovery and Memory search return results with next_cursor. The SIEM pull POST /v1/audit/export returns a numeric next_after you resend as after; the ordinary GET /v1/audit ledger read pages like everything else. Each generated endpoint page shows the exact response shape.

Streaming

Session streams use SSE. The current alpha replays every stored event after the supplied cursor in internal pages and then stays live. Resume a disconnected or stalled stream with Last-Event-ID; see Events.

Generated API reference

The API reference section in the sidebar is generated from the same OpenAPI document the platform serves at /api/openapi.json: one page per endpoint, for every resource group. A repository gate re-fetches the document from the real worker and fails when the committed snapshot no longer matches. It runs on the check:heavy cadence rather than on every landing, so these pages can briefly trail a freshly landed contract change. The handwritten pages in this section explain the conventions the generated pages assume.

Next steps

Authentication and versions

Scope API keys to a Workspace, pin a dated wire version, and read the auth headers.

Sessions

Open a Session, drive a Run, and stream its events over SSE.