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.

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_outdated, sign_in_outdated No key, or the key is not valid: revoked, made before keys could be revoked, or a console sign-in from before sign-ins expired. 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, 503 no_capacity and others No model could take the request in time, or a service it needs is down. Retry later.

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