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.