Skip to content

API

Fadenstack serves the OpenAI API at /v1 on your server. Any OpenAI client works: set the base URL and the key.

Routes

Route What it does
POST /v1/chat/completions Chat, streamed or whole. Chat completions
POST /v1/embeddings Embeddings. Embeddings and rerank
POST /v1/rerank Reranks documents for a query. Embeddings and rerank
GET /v1/models The models you may use. Models
/v1/agents/{agent}/… Requests on behalf of an agent; the SDKs use these. Agents

The server has more routes under /v1 that the chat and the SDKs use, for example for server-side chat sessions, memory and attachments. The SDKs wrap them; a full reference will follow.

Authentication

Send a key in the Authorization header:

Authorization: Bearer <key>
Key Get it Use it for
API token Your profile in the chat or the console, under API token. See Your first API call. Your own apps and scripts
Agent sign-in The SDK, for a user on a device The agent routes only. See Agents on the server.

A key acts as its user. Which models it may use is decided by the server, not by the key.

The gateway also accepts a console sign-in. It stops working within 30 to 60 seconds of the user logging out, changing the password, or being suspended or losing a role.

Interactive API reference

The server's own schema pages (/api/docs, /api/redoc and /api/openapi.json for the console's admin API, and /gateway-docs/ for the gateway) open only in a browser that is signed in to the console as a user who may see observability data. A bearer token does not open them. GET /v1/services needs an API token.

Request IDs

Send X-Request-Id and the server returns it on the response; otherwise the server makes one up and returns it as x-request-id. Quote it when you report a problem.

Errors

Errors use OpenAI's envelope. Where Fadenstack has more to say, a faden object sits next to error.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Model alias 'team-asistant' is not available for this tenant.",
    "param": "model",
    "code": "model_not_found"
  }
}
Status Codes Means
400 missing_model, validation_error, invalid_json, invalid_header, model_kind_mismatch, unsupported_parameter The request is malformed, or uses a model for the wrong kind of request (for example chat on an embeddings model)
401 missing_authorization, invalid_token, api_token_revoked, api_token_expired, api_token_outdated, sign_in_ended, sign_in_outdated No key, or the key is not valid: revoked or expired, made before keys could be revoked, or a console sign-in that has ended (a logout, a password change or reset, a suspension, a role taken away) or is from before sign-ins could end. Make a new key, or sign in again.
403 user_inactive, agent_not_granted, agent_not_published, agent_retired, agent_token_not_allowed The key's user was deactivated, or you may not use this agent or route
404 model_not_found, agent_not_found No such model or agent for you
413 request_too_large The body is larger than 2 MiB
422 policy_blocked A rule of the organisation refused the request. See Chat completions
429 rate_limit_rpm, rate_limit_tpm Too many requests or tokens per minute for your organisation. Wait for Retry-After seconds.
502 upstream_authentication_failed The model's provider refused the server's own credentials for it. Your key is fine; an administrator has to fix the provider's key. Do not sign the user in again.
502, 503 no_capacity, pii_service_unavailable, access_check_failed and others No model could take the request in time, or a service it needs is down, or your access could not be checked. Retry later. See also Personal data.

When a stream breaks off, its last event before [DONE] is an error object in the same shape.