Skip to main content
Plain HTTP is the public contract. The TypeScript SDK, CLI, and MCP expose interfaces over the same operations; they do not define separate resource models.

Product model

Understand the resource hierarchy and authority boundaries before selecting operations.

Canonical lookup

Find current ID prefixes, statuses, event families, and other hand-maintained contract tables.

​
Request conventions

Ordinary customer API keys are Workspace-bound; examples do not send a Workspace selector header. Use generated OpenAPI for exact paths, fields, defaults, limits, pagination, operation IDs, and errors. A hand-written example that disagrees with the generated contract is stale.

​
Session requests

Create a Session with an Agent selector and environment_id. Admission resolves and freezes the AgentVersion and Environment authority for that Session. Authenticated server context supplies actor attribution for later drive events. Request completion means accepted input. Read Run and Session settlement from durable events.

​
Identifiers

Every Checkfu resource ID is a prefix, an underscore, and 32 lowercase hex characters. The prefix tells you the resource type, so a mismatched prefix is 400 validation.malformed rather than being read as a different resource. A well-formed ID of the expected type that does not exist is 404 validation.not_found. whsec_ is not a resource ID. It prefixes a webhook signing secret, and the whole string including the prefix is the key. Generated OpenAPI carries the exact type for every field; use it when a prefix is not listed here.

​
Errors and retries

Switch on stable error types, not human-readable text. Retry only when the operation and error contract permit it, and reuse the same Idempotency-Key for the same logical mutation. An uncertain provider effect is not a normal retryable request failure. It remains indeterminate until the trusted effect owner reconciles it.

​
Availability

The existence of an operation does not prove availability for a deployment, provider, or runtime tuple. Check capability status and the exact prerequisites before depending on it.