> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Use Checkfu's served HTTP contract and its generated SDK, CLI, and MCP projections.

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.

<CardGroup cols={2}>
  <Card title="Product model" href="/concepts/product-model">Understand the resource hierarchy and authority boundaries before selecting operations.</Card>
  <Card title="Canonical lookup" href="/reference/lookup">Find current ID prefixes, statuses, event families, and other hand-maintained contract tables.</Card>
</CardGroup>

## Request conventions

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer <token>
Checkfu-Version: <supported version>
Content-Type: application/json
Idempotency-Key: <stable key for a retryable mutation>
```

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`.

| Prefix | Resource |
| - | - |
| `org_` | Organization |
| `wrkspc_` | Workspace |
| `akey_` | API key |
| `prin_` | Principal |
| `pgrp_` | PrincipalGroup |
| `agent_` | Agent |
| `aver_` | AgentVersion |
| `env_` | Environment |
| `sess_` | Session |
| `sthr_` | SessionThread |
| `run_` | Run |
| `ratt_` | RunAttempt |
| `evt_` | Session event |
| `qst_` | Agent question |
| `conn_` | Connection |
| `vlt_` | Vault |
| `skl_` | Skill |
| `cpt_` | Concept |
| `ftree_` | FileTree |
| `mnt_` | Mount |
| `apol_` | ActionPolicy |
| `comp_` | Computer |
| `scrn_` | Screen |

`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](/getting-started/status) and the exact prerequisites before depending on it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.