> Keiro Labs API documentation - API Reference
> Page: https://docs.keirolabs.ai/api-reference.html
> Markdown: https://docs.keirolabs.ai/api-reference.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

# API reference

Keiro exposes three authenticated completion surfaces at one public base URL:

```text
https://api.keirolabs.ai/v1
```

Choose the wire format that already fits your application. The model and
account determine which capabilities are available; the endpoint does not
expose private routing or provider details.

## Completion endpoints

| Surface | Endpoint | Primary input | Generated text |
|---|---|---|---|
| [Responses](responses.md) | `POST /responses` | `input` or typed input items | SDK `output_text`, or text parts in `output` |
| [Chat Completions](chat-completions.md) | `POST /chat/completions` | `messages` | `choices[0].message.content` |
| [Messages](messages.md) | `POST /messages` | `messages`, with optional top-level `system` | Text blocks in `content` |

All three surfaces support buffered responses and server-sent event streams.
Function tools and image input use the native content shape for each surface.

## Discovery endpoint

Use `GET /v1/models` with the same bearer authentication to list the public
model IDs available to the current key. The result is account-scoped and can
include effective static limits for each model.

See [Models](models.md) for a runnable request and model-selection guidance.

## Utility endpoints

Use `POST /messages/count_tokens` to estimate the prompt size of a Messages
request before sending it. The estimate uses the same per-part minimums that
admission and billing apply, so multimodal estimates match what a real
request is charged. See [Messages](messages.md).

Other operational routes reachable on the base URL — tool-output submission,
stream resume, request cancel, and capability discovery — are not yet part of
the documented public contract. Do not build against them until they appear
in this reference.

## Shared request contracts

- Authenticate with `Authorization: Bearer <api-key>`; see [API auth](api-auth.md).
- Use only a model returned for the current key; see [Models](models.md).
- Add `Idempotency-Key` when retrying a logical operation must not execute it
  twice; see [Idempotency](idempotency.md).
- Read request IDs and rate-limit headers for operational handling; see
  [Rate and spend limits](rate-and-spend-limits.md).
- Match failures on the machine-readable error `code` and `type`, not message
  text; see [Errors](errors.md).
- Streams carry documented per-effort time entitlements: a stream that is
  actively working is never ended before its effort tier's wall-clock ceiling;
  see [Streaming](streaming.md#stream-lifetime-and-time-entitlements).

## Compatibility boundary

Keiro is OpenAI-compatible where documented, but compatibility does not mean
that every parameter from every SDK or vendor API is accepted. Unknown or
unsupported fields fail closed under the current strict validation contract.
Build against the fields documented for the selected surface and treat a
capability error as a request or model-selection issue, not as permission to
fall back silently.

## Related pages

- [Tool calling](tool-calling.md)
- [Images and vision](images-vision.md)
- [Streaming](streaming.md)
- [SDKs](sdks.md)