Chat Completions

POST /v1/chat/completions
Authorization: Bearer sk-tbl-<your-key>
Content-Type: application/json

Request and response shapes follow the OpenAI Chat Completions API. Unknown OpenAI fields are accepted and ignored. TAIBLES-specific options live under a top-level taibles object (via the SDK extra_body mechanism where applicable).

Request body

Field	Required	Description
model	yes	Agent id (default-assistant, slug, UUID) or chat LLM URL — see Agents and models
messages	yes	Non-empty array of chat messages. The last message must have role user or tool
stream	no	If true, respond with Server-Sent Events
tools	no	OpenAI-style tool definitions for client-executed tools
tool_choice	no	Accepted for compatibility
temperature, top_p, max_tokens, max_completion_tokens, stop, user	no	Accepted for compatibility where applicable
taibles	no	TAIBLES extensions (see below)

Messages

Standard roles (system, user, assistant, tool) are supported. Content may be a string or OpenAI-style multipart content; text is taken from the message for the agent turn.

If you omit taibles.conversation_id, TAIBLES creates a new conversation and seeds server-side history from the messages before the final turn. The final user/tool turn is submitted as the new message.

Streaming

Set "stream": true. The response is text/event-stream with OpenAI-style chunks, ending with data: [DONE]. Mid-stream failures are emitted as an OpenAI-style error event instead of a silent close.

Client-executed tools

Pass OpenAI tools (function definitions). When the agent needs a client-side tool, the completion finishes with finish_reason: "tool_calls" and assistant tool_calls in the message (or streaming deltas). Send tool results back as role: "tool" messages (last message(s) must be tool results) to continue the turn.

Server-side agent tools (integrations, knowledge, automations, and so on) run inside TAIBLES and do not require this loop.

TAIBLES extensions

Send via top-level taibles (Python/JS SDKs: extra_body={"taibles": {...}}).

Field	Description
conversation_id	UUID of an existing conversation for server-side continuity. Must be a valid UUID if set. Omit to start a new conversation.
builtin_tools	Optional list of builtin tool categories the assistant may use: memory, files, actions, automations. Omit or null → all categories allowed.

Example:

{
  "model": "default-assistant",
  "messages": [{"role": "user", "content": "Remember that our Q3 kickoff is Monday."}],
  "taibles": {
    "conversation_id": "01234567-89ab-cdef-0123-456789abcdef",
    "builtin_tools": ["memory", "files"]
  }
}

Python:

completion = client.chat.completions.create(
    model="default-assistant",
    messages=[{"role": "user", "content": "Continue where we left off."}],
    extra_body={
        "taibles": {
            "conversation_id": conversation_id,
        }
    },
)

Response

Non-streaming responses are OpenAI chat.completion objects. Streaming responses are chat.completion.chunk events.

Conversation id

Every successful completion exposes the conversation id so you can continue server-side:

• Response header: X-Taibles-Conversation-Id
• Body field: taibles.conversation_id (also present on the final streaming chunk)

Echo that value back as taibles.conversation_id on the next request to keep state on the server.

Finish reasons

Value	Meaning
stop	Normal completion
tool_calls	Assistant requested client-executed tools

Errors

Errors use an OpenAI-style envelope. Common cases:

HTTP	Type / code	When
400	invalid_request_error	Invalid body, empty messages, bad conversation_id, agent without chat support
401 / 403	auth errors	Missing or invalid API key
404	invalid_request_error / model_not_found	Unknown model
429	rate_limit_error / rate_limit_exceeded	Rate limited