OpenAI-Compatible API

The STAIR OpenAI-compatible API lets any OpenAI client call a STAIR agent by name over HTTPS, with streaming and multi-turn sessions.

How the OpenAI-compatible API works in STAIR

STAIR exposes its agents through the same request and response format as the OpenAI Chat Completions API. An existing OpenAI SDK or tool works after you change two things: the base URL and the API key.

The base URL for an OpenAI SDK is https://<your STAIR host>/ee/v1. The examples on this page use https://stair.example.com.

Key rules:

• model is the agent name. The value is the Agent Name exactly as it appears in Agents, for example Demo · Support Triage. It is not the name of an LLM: the agent's own model, instructions, toolsets, skills and sub-agents are used.
• Use the plain agent name. STAIR Chat shows agents with a connection prefix, such as DEV.Demo · Support Triage. The prefix belongs to STAIR Chat only; do not send it in model.
• Access follows the ACL. GET /ee/v1/models lists only the agents your key or SSO session may use, and a request to any other agent fails with 403 or 404.
• Only chat completions and models. There are no /responses or /files endpoints. Files and images travel inline in the message as content parts.

How to authenticate API requests

Every request needs one of these headers:

A personal API key acts with the roles and permissions of the user who created it. A service account key acts as the service account, which needs Execute Access on the agent. See API Keys and Service Accounts for how to create both.

How to send a chat completion request

Send a POST request with the agent name in model and the conversation in messages:

curl https://stair.example.com/ee/v1/chat/completions \
  -H "Authorization: Bearer $STAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: helpdesk-ticket-4711" \
  -d '{
    "model": "Demo · Support Triage",
    "messages": [
      {"role": "user", "content": "I was charged twice for my Brightpath Cloud subscription this month."}
    ]
  }'

The response is a standard chat.completion object. The answer is in choices[0].message.content, and token counts are in usage.

With the OpenAI Python SDK, set base_url and api_key:

from openai import OpenAI

client = OpenAI(
    base_url="https://stair.example.com/ee/v1",
    api_key="aip_sk_...",  # sent as Authorization: Bearer
)

response = client.chat.completions.create(
    model="Demo · Support Triage",
    messages=[{"role": "user", "content": "How long is a password reset link valid?"}],
    extra_headers={"X-Session-Id": "helpdesk-ticket-4711"},
)
print(response.choices[0].message.content)

To list the agents you can call:

curl https://stair.example.com/ee/v1/models \
  -H "Authorization: Bearer $STAIR_API_KEY"

Each entry has id (the agent name, to use as model), description and, when the agent's model has a context window set, context_length.

How to stream a response

Set "stream": true to receive the answer as Server-Sent Events. Each event is a chat.completion.chunk in the OpenAI format, and the stream ends with data: [DONE]. Add "stream_options": {"include_usage": true} to receive one more chunk with the total token usage before [DONE].

curl -N https://stair.example.com/ee/v1/chat/completions \
  -H "STAIR-API-KEY: $STAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Demo · Finance Analyst",
    "messages": [{"role": "user", "content": "What is 5% annual interest on 12,000 EUR over 3 years?"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

stream = client.chat.completions.create(
    model="Demo · Finance Analyst",
    messages=[{"role": "user", "content": "What is 5% annual interest on 12,000 EUR over 3 years?"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\nTokens:", chunk.usage.total_tokens)

How to continue a conversation with X-Session-Id

Send the same X-Session-Id header value with every request of one conversation. Without the header, each request opens a new session. The response carries the session id in its X-Session-Id header, so a client that sent no header can read the generated id and reuse it.

As with any OpenAI-compatible API, send the previous turns in messages on every request. A session holds one request at a time: a second request with the same X-Session-Id while the first is still running is rejected.

Use one session id per conversation, for example a ticket number or a UUID. Do not share one id between unrelated users or conversations.

How to send files and images

Files and images go inline in messages, as content parts of a user message:

{
  "model": "Demo · Support Triage",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "The customer attached this screenshot of the error."},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
    ]
  }]
}

• Images: a image_url part with a data: URI (Base64) or an https URL.
• Documents: a file part with file_data (Base64) and filename. Whether the agent can read the document depends on the agent's model.

There is no upload endpoint and no file id to reference later. Send the file again in a later request if the agent needs it.

Chat completions request reference

Troubleshooting the OpenAI-compatible API

401 "Invalid access token"

The key is missing, mistyped, revoked or expired, or the Authorization header is not in the Bearer <key> format. Create a new key in Connections → Tokens or in Service Accounts and send it in Authorization: Bearer or STAIR-API-KEY.

403 or 404 "Model '…' not found or access denied"

The model value does not match an agent you may use, or the key's holder has no access to it. Check the spelling, including spaces and the · character, and remove a STAIR Chat prefix such as DEV.. Call GET /ee/v1/models to see the exact names. For a service account, ask an administrator to grant Execute Access on the agent.

Request rejected because the session is busy

A request with the same X-Session-Id is still running. Wait for the first answer, or use a different session id for parallel requests.

Every answer forgets the previous turn

The previous turns were not sent. Include the earlier user and assistant messages in messages, and send the same X-Session-Id on each request.

FAQ

What do I put in the model field?

Put the agent name exactly as it appears in Agents, for example Demo · Support Triage. STAIR runs that agent with its own model, instructions and tools.

Can I use the official OpenAI SDKs?

Yes. Set the base URL to https://<your STAIR host>/ee/v1 and the API key to an aip_sk_ key. Use the chat completions methods; the Responses and Files APIs are not available.

Does the API support streaming?

Yes. Set stream: true to receive Server-Sent Events in the OpenAI chunk format, and stream_options.include_usage: true to get token usage at the end of the stream.

How do I keep a multi-turn conversation together?

Send the same X-Session-Id header with every request and include the previous turns in messages. Without the header, each request starts a new session.

How do I send a file to an agent?

Put it inline in the user message as a content part: image_url with a Base64 data: URI for images, or file with Base64 file_data for documents. There is no separate upload endpoint.

Related

• API Keys and Service Accounts
• AI Agents
• MCP Gateways
• Security and Access Control
• STAIR Chat