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

# API reference

## Base URL

Every request goes to your workspace's subdomain (`acme` in the examples):

```
https://acme.klef.ai/api
```

## Authentication

[Create an API key](/docs/how-to/manage-api-keys) under **Settings > API keys**, then send it as a bearer token in the `Authorization` header:

```bash theme={null}
curl https://acme.klef.ai/api/workers \
  -H "Authorization: Bearer klef_sk_..."
```

* A key belongs to one workspace, and only works on that workspace's subdomain.
* A key can do only what its scopes allow, and its scopes never exceed the [permissions](/docs/reference/roles-and-permissions) of the member who created it.
* A missing, invalid, expired, or revoked key gets a `401`. A key without the permission an endpoint needs gets a `403`.
* API keys can't create, rotate, or revoke API keys. Those endpoints need a signed-in session.

## Responses

Every JSON response has the same envelope. A single resource comes back under `result`:

```json theme={null}
{
  "result": { "id": "0199b2a4-…", "name": "Engineering" },
  "errors": []
}
```

A list comes back under `results`, with cursor pagination. Pass `nextCursor` back as `cursor` to get the next page:

```json theme={null}
{
  "results": [ … ],
  "errors": [],
  "pagination": { "nextCursor": "…", "limit": 50, "hasMore": true, "total": 212 }
}
```

A failed request keeps its HTTP status, returns `null` for `result`, and lists what went wrong in `errors`:

```json theme={null}
{
  "result": null,
  "errors": [
    { "errorCode": "connection_not_found", "errorMessage": "Connection not found." }
  ]
}
```

`errorCode` is stable, so branch on it rather than on `errorMessage`.

## Concurrent updates

Resources that more than one person can edit return an `ETag` header. To update one, send that value back in `If-Match`. A request without it gets a `428`, and a request made against an older version gets a `412`: fetch the resource again and retry.

<CardGroup cols={2}>
  <Card title="Manage API keys" icon="key" href="/docs/how-to/manage-api-keys">
    Create, rotate, and revoke keys.
  </Card>

  <Card title="Roles and permissions" icon="shield-halved" href="/docs/reference/roles-and-permissions">
    The scopes a key can hold.
  </Card>
</CardGroup>