APIChat API v1

Build conversations that can keep working.

Stream AI agent, workflow, and RAG executions into your application with one authenticated interface, resumable checkpoints, and structured progress events.

Communication protocol

Server-Sent Events

UTF-8 event stream over HTTPS. Each frame contains a JSON payload in its data: field.

Quick start

One request, one live stream

Send a message to an agent, workflow, or RAG target. The connection remains open while the run emits lifecycle events, execution steps, and a final Markdown response.

1. Authenticate

Send your API key with every request.

2. Start a run

Choose one target and provide content.

3. Read events

Parse each SSE data frame as JSON.

curl --no-buffer --request POST \
  "http://localhost:1000/api/chat" \
  --header "x-api-key: $CHATBOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "7496579023959494656",
    "query": "Summarize our support policy."
  }'

Authentication

API key

Every endpoint on this page requires an active API key. Use either header below. When both are present, x-api-key takes precedence.

x-api-keyRecommended

x-api-key: sk_live_0b••••••••••••••••b0da

Status	Meaning	Response
401	Key is missing, invalid, or revoked.	{ "detail": "..." }
403	The account AI credit quota is exhausted.	{ "detail": "..." }

Request model

ChatRequest

All fields are JSON. Requiredness is conditional: a new run needs at least one target and either a non-empty query or one attachment.

Property	Type	Required	Description
query	string	Conditional	User prompt. Required when files is empty on a new run. Defaults to an empty string.
agent_id	integer \| string	Conditional	Agent target. At least one target identifier is required for a new run.
workflow_id	integer \| string	Conditional	Workflow target. At least one target identifier is required for a new run.
rag_id	integer \| string	Conditional	RAG target. Execution priority is RAG, then workflow, then agent when several targets are sent.
conversation_id	string	On resume	Existing conversation ID for resume. Generated as a UUID when omitted on a new run.
history	HistoryMessage[]	No	Stateless prior messages supplied by the client. Defaults to an empty array.
files	FileAttachment[]	Conditional	Remote Blob URLs. At least one file is required when query is empty.
is_resume	boolean	No	Resume an interrupted checkpoint. Defaults to false and requires conversation_id when true.

History message

Each item in history contains:

sender *: Required. human or ai
message *: Required text content

File attachment

Each item in files contains:

url *: Required direct or Blob URL
name: Optional file name with extension
mime_type: Optional MIME content type hint

POST/api/chatSSE

Start or resume a chat

Starts a background execution and opens its event stream. Omit conversation_id for a new UUID, or send conversation_id with is_resume set to true to continue from a failed checkpoint.

Content-Typeapplication/json request; text/event-stream response

BodyChatRequest

New runOne target plus a query or at least one file is required.

Resumeconversation_id and is_resume: true are required; stored target and query can be restored.

Request body

{
    "agent_id": "7496579023959494656",
    "query": "Compare the refund options.",
    "history": [
        {
            "sender": "user",
            "message": "I am reviewing the annual plan."
        }
    ],
    "files": []
}

Responses

200SSE stream opened.

400Invalid target or resume state.

401API key failure.

403Quota exhausted.

422Invalid request body.

GET/api/chat/resume/{conversation_id}SSE

Resume from checkpoint

Restarts an interrupted execution from its persistent SQLite checkpoint. The target and query are restored from stored conversation metadata.

Path parameterconversation_id — required string identifier.

BodyNone.

Use whenExecution failed or was interrupted and a persistent checkpoint exists.

Resume request

curl --no-buffer \
  "http://localhost:1000/api/chat/resume/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

Responses

200Resumed SSE stream.

400Completed run or no checkpoint.

401API key failure.

403Quota exhausted.

GET/api/chat/stream/{conversation_id}SSE

Reconnect to a run

Reattaches to an existing in-memory run after a network interruption. Buffered steps and a completed response, when available, are replayed before live events continue.

Path parameterconversation_id — required string identifier.

BodyNone.

Use whenThe SSE connection dropped but the background run still exists.

Reconnect request

curl --no-buffer \
  "http://localhost:1000/api/chat/stream/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

Responses

200Reconnected SSE stream.

401API key failure.

403Quota exhausted.

404No run found in memory.

POST/api/chat/stop/{conversation_id}JSON

Stop an active run

Cancels the background task and closes execution. This endpoint returns regular JSON and reports whether an active run was found to stop.

Path parameterconversation_id — required string identifier.

BodyNone.

ResponseA status, message, and metadata object containing conversation_id.

Request and response

curl --request POST \
  "http://localhost:1000/api/chat/stop/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

{
    "status": 200,
    "message": "Chat run stopped successfully.",
    "metadata": {
        "conversation_id": "4e982ba9-3a98-45de-9c17-796b77d76b39"
    }
}

Responses

200Stopped, or no active run found.

401API key failure.

Streaming contract

SSE event lifecycle

The API does not use the SSE event: field. Inspect the JSON type property inside each data: frame. Native browser EventSource cannot send the required authentication header, so browser clients should consume the stream with Fetch or an SSE library that supports custom headers.

SSE wire format

data: {"type":"session.started","message":"Session started...","metadata":{"conversation_id":"4e9...","is_resume":false}}

data: {"type":"execution.started","message":"Execution started","metadata":{"conversation_id":"4e9..."}}

data: {"type":"step.completed","message":"Agent 'Support' started...","step":{"status":"completed","name":"agent_started"},"metadata":{"conversation_id":"4e9..."}}

data: {"type":"response.completed","message":"Generated response","response":{"status":"completed","answer":{"content":"...","format":"markdown"}},"metadata":{"conversation_id":"4e9..."}}

data: {"type":"execution.completed","message":"Chat processing completed","metadata":{"conversation_id":"4e9..."}}

session.started

Initial handshake for a new or reconnected stream.

message, metadata.conversation_id, metadata.is_resume?

session.resumed

Initial handshake when continuing from a persistent checkpoint.

message, metadata.conversation_id, metadata.is_resume

execution.startedMay emit

Signals background execution. A very fast run can begin before the subscriber attaches.

message, metadata.conversation_id

step.startedMay emit

An execution step is in progress. Reconnected clients can receive replayed steps.

message, step, metadata.conversation_id

step.completedMay emit

An execution step completed. Step details vary by agent, workflow, and RAG implementation.

message, step.id, step.name, step.title, step.status, step.input?, step.output?, metadata

response.started / response.deltaMay emit

Incremental response events supported by compatible execution paths.

message, metadata.conversation_id

response.completed

Contains the final Markdown answer and optional RAG sources.

response.status, response.answer.content, response.answer.format, response.sources?, metadata

step.failedMay emit

Reports an execution error after the SSE connection has started.

message, metadata.conversation_id, metadata.message_id?

execution.completed

Terminal event for success, failure, or a user-requested stop.

message, metadata.conversation_id, metadata.message_id?

Keep reading until execution.completed. The successful answer is in response.answer.content and uses Markdown. RAG responses can also contain response.sources.

Errors

Two error channels

Before streaming

HTTP JSON error

Authentication, quota, validation, missing checkpoint, and unknown run failures use HTTP status codes with a JSON detail field.

During streaming

SSE failure event

Once HTTP 200 has started, execution failures arrive as step.failed, followed by execution.completed.

Stream failure

data: {"type":"step.failed","message":"An error occurred while processing the chat query: ...","metadata":{"conversation_id":"4e9..."}}

data: {"type":"execution.completed","message":"An error occurred while processing the chat query: ...","metadata":{"conversation_id":"4e9..."}}