Skip to main content
POST

Authorizations

Authorization
string
header
required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Headers

X-Trace-Id
string

Same as the trace_id body field, checked first.

X-Trace-Session-Id
string

Same as the trace_session_id body field, checked first.

Query Parameters

trace_id
string

Same as the trace_id body field, checked after the header.

trace_session_id
string

Same as the trace_session_id body field, checked after the header.

Body

application/json

Request body to send a chat message.

query
string
required

The user's message.

inputs
object
required

Values for the app's input variables, keyed by variable name. Use the input variables defined in the version currently deployed to the target environment.

Pass a file object for a single-file variable, or an array of file objects for a file-list variable. Each file object has the same structure as an item in files.

user
string
required

End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same user. See End User Identity.

response_mode
enum<string>
default:blocking

How the response is delivered.

  • streaming: events arrive as the run produces them. Use it for anything longer than a quick reply.
  • blocking: one response once the run completes.
Available options:
streaming,
blocking
conversation_id
string

ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a conversation_id to send with the next message. To resume an earlier conversation, get its ID from List Conversations.

files
object[]

Files to attach to the message. For a local file, first upload it via Upload File, then reference the returned id as upload_file_id with transfer_method: local_file.

trace_id
string

Trace identifier propagated to observability data. Letters, digits, hyphens, and underscores are accepted, up to 128 characters. A value that does not match is skipped, not rejected.

trace_session_id
string

Trace session identifier propagated to observability data, 1 to 200 characters after trimming.

Required string length: 1 - 200

Response

The content type and structure depend on the response_mode parameter in the request.

  • If response_mode is blocking, returns application/json with a ChatCompletionResponse object.
  • If response_mode is streaming, returns text/event-stream with a stream of Server-Sent Events.
event
string

Always message.

task_id
string

Task ID for this run. In blocking mode it arrives only in this final body, so Stop Chat Message Generation is practical only with streaming.

id
string

Message ID.

message_id
string

Message ID (same value as id).

conversation_id
string

Conversation the turn belongs to; a new conversation's ID when conversation_id was omitted.

mode
string

Always advanced-chat.

answer
string

The complete answer text.

metadata
object

Run metadata; contains usage with token counts, prices, and latency.

created_at
integer

Run start time as a Unix timestamp in seconds.