API reference
Keiro exposes three authenticated completion surfaces at one public base URL:
On this page 1 of 7
https://api.keirolabs.ai/v1
OpenAI-format clients take this /v1 base URL. Messages-format SDKs and tools that append /v1/messages themselves take the API root without the /v1 suffix; a base URL that already ends in /v1 then produces a 404. Keiro does not read the anthropic-version or anthropic-beta request headers; see Messages.
Choose the wire format that already fits your application. The model and account determine which capabilities are available. Each endpoint accepts its own request fields, tool types and content shapes, so check the page for the surface you call.
Completion endpoints#
| Surface | Endpoint | Primary input | Generated text |
|---|---|---|---|
| Responses | POST /responses | input or typed input items | SDK output_text, or text parts in output |
| Chat Completions | POST /chat/completions | messages | choices[0].message.content |
| Messages | 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.
What differs by surface#
| Capability | Where it differs |
|---|---|
| Images in tool results | Responses function_call_output and Messages tool_result take image parts. Chat Completions tool messages are text-only. See Images and vision. |
| Hosted web search | {"type": "web_search"} is documented on Responses and Chat Completions. See Tool calling. |
seed, logprobs, top_logprobs, n | On Chat Completions, an integer seed is accepted and ignored, and logprobs: true, top_logprobs above 0 and n above 1 are refused with a 400 naming the field. See Chat Completions. |
| Progress while the model is silent | All three surfaces, each in its own shape: a chunk on Chat Completions, events on Responses, ping on Messages. See Streaming. |
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 for a runnable request and model-selection guidance.
Utility endpoints#
Use POST /messages/count_tokens to size the prompt of a Messages request before sending it. A body the Messages endpoint accepts is counted the way the request is billed: message text, tool definitions, tool history and the same per-part minimums for images and documents that admission and billing apply. See Messages.
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.
These paths are not offered. With a valid key they answer 404 with error code not_found; without one, the 401 comes first:
GET /v1/models/{model}. Read the model's entry fromGET /v1/modelsinstead; an SDK's model-retrieve call fails.GET /v1/responses/{response_id},DELETE /v1/responses/{response_id},GET /v1/responses/{response_id}/input_itemsandPOST /v1/responses/{response_id}/cancel.POST /v1/responses/compactandPOST /v1/responses/input_tokens.POST /v1/messages/batches,GET /v1/messages/batchesand every path under them.
Shared request contracts#
- Authenticate with
Authorization: Bearer <api-key>on every surface;X-API-Key: <api-key>is also accepted. See API auth. - Use only a model returned for the current key; see Models.
- Add
Idempotency-Keywhen retrying a logical operation must not execute it twice; see Idempotency. - Read request IDs and rate-limit headers for operational handling; see Rate and spend limits. Every response under
/v1carriesX-Request-Id. Responses under/v1/messagesalso carry the same value asrequest-id, the header Messages-format SDKs read. - Match failures on the machine-readable error
codeandtype, not message text; see Errors. - A request lives as long as the model keeps working: no wall-clock limit ends a stream or a non-streaming request, and a non-streaming reply still running 30 seconds in, once the request has been sent to a model, arrives after leading whitespace; see Streaming.
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.