Onyx AI endpoint reference

Send chat requests to POST /v1/chat/completions. The API uses a chat-completions request and response shape with messages, choices, and optional streaming. Use the endpoints and fields described here when configuring a client.

Include ?databaseId=... to select the database context. Requests remain subject to your credentials, database access, and model availability. For a self-hosted service, substitute its AI base URL.

Organization-funded usage counts agentic tasks: one user request includes its model and tool calls, and each follow-up counts separately. Plans include a rolling seven-day allowance, with additional agentic tasks billed individually when billing is enabled. Reported token usage is diagnostic and does not determine agentic task charges. See pricing.

Use a Firebase ID bearer token or the paired database API-key headers. Keep API keys and secrets on your application server. Use the same identity when registering and executing a script approval.

Authorization: Bearer <firebase-id-token>

# Alternatively, send both database credentials:
x-onyx-key: <database-api-key>
x-onyx-secret: <database-api-secret>

Choose an available model identifier from GET /v1/models, or the identifier of an agent you have published in your organization. Replace the placeholders before running this request:

curl --no-buffer 'https://ai.onyx.dev/v1/chat/completions?databaseId=YOUR_DATABASE_ID' \
  -H "Authorization: Bearer $ONYX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "stream": true,
    "messages": [{"role": "user", "content": "Summarize the tables in this database."}]
  }'

The response is a stream of server-sent events. Read complete events separated by a blank line; a network read may contain only part of an event. Finish when you receive data: [DONE].

Required fields are model and messages. Set stream to true for streaming; it defaults to false. The request also accepts temperature, top_p, max_tokens, tools, and tool_choice; support depends on the selected model and workflow.

For a non-streaming response, read choices[0].message.content. The response includes the model, completion identifier, finish reason, and reported usage. This is an illustrative response:

{
  "id": "request-id",
  "object": "chat.completion",
  "created": 1791072000,
  "model": "YOUR_MODEL_ID",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Your database contains..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 120, "completion_tokens": 30, "total_tokens": 150}
}

Streaming responses use text/event-stream. JSON data events contain choices[].delta. Append text from assistant content deltas; keep tool events separate. A final choice with finish_reason: "stop" precedes the completion marker.

data: {"id":"request-id","object":"chat.completion.chunk","created":1791072000,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{"role":"assistant","content":"Your database contains..."}}]}

data: {"id":"request-id","object":"chat.completion.chunk","created":1791072000,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Ignore keep-alive comments. Handle event: error as a failed generation, even if a completion marker follows it. Preserve the request ID when reporting a failure; an ended stream alone does not prove successful execution.

Assistant deltas can include tool_calls, with an identifier, function name, and JSON-encoded function.arguments string. Preserve the emitted names and identifiers. Available tools depend on the model or agent workflow.

Onyx executes its server-managed tools and emits their results as deltas with role: "tool", tool_call_id, and content. Do not execute those calls a second time in your client. Client-handled requests such as request_script_approval and request_user_approval require a user decision.

When continuing a conversation, retain the messages and tool context. For a tool handled by your client, return its result with the matching tool_call_id. Follow the approval metadata flow below for workflow approval requests.

Script mutation checks can require approval before execution. Present the exact proposed script and findings to the user. After approval, register the script using the same credentials:

POST /api/script-approvals
Content-Type: application/json
Authorization: Bearer <firebase-id-token>

{"script":"await db.save('Account', { id: 'acct_1', name: 'Checking' });"}

The response contains normalizedScript, requiresApproval, findings, and expiresAtIso. Required approvals are scoped to the identity and normalized script and currently expire after two minutes. Registration does not itself execute the script or grant database permissions.

For request_script_approval, retain the assistant’s tool call and send a tool message with its matching tool_call_id and a JSON-encoded decision in content, such as JSON.stringify({ approved: true }). The decision does not replace script registration where the execution guard requires it.

For workflow user approvals that supply an approval ID, continue the chat with the prior context and a user message containing the requested approval ID and the decision in metadata:

{
  "role": "user",
  "content": "Approved",
  "metadata": {"approval_id": "ID_FROM_APPROVAL_REQUEST", "approved": true}
}

For a denied request, send approved: false and do not register script approval. If approval expires before execution, obtain a fresh decision instead of assuming the earlier grant still applies.

• GET /v1/models lists the configured model identifiers in data[].id.
• GET /v1/models/{modelId} returns model metadata. It does not perform an inference or verify provider readiness.
• POST /api/script-approvals registers an identity-scoped script approval as described above.

Publish reusable workflows in Agent Builder, then use their model identifier when calling chat completions.