Skip to main content
POST
/
chat-messages
A valid request URL is required to generate request examples
{
  "event": "message",
  "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
  "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
  "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
  "mode": "advanced-chat",
  "answer": "iPhone 13 Pro Max specs are listed here:...",
  "metadata": {
    "usage": {
      "prompt_tokens": 1033,
      "prompt_unit_price": "0.001",
      "prompt_price_unit": "0.001",
      "prompt_price": "0.0010330",
      "completion_tokens": 128,
      "completion_unit_price": "0.002",
      "completion_price_unit": "0.001",
      "completion_price": "0.0002560",
      "total_tokens": 1161,
      "total_price": "0.0012890",
      "currency": "USD",
      "latency": 0.7682376249867957
    },
    "retriever_resources": [
      {
        "position": 1,
        "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
        "dataset_name": "iPhone",
        "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
        "document_name": "iPhone List",
        "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
        "score": 0.98457545,
        "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
      }
    ]
  },
  "created_at": 1705407629
}

Authorizations

​
Authorization
string
header
required

API Key authentication. For all API requests, include your API Key in the Authorization HTTP Header, prefixed with Bearer. Example: Authorization: Bearer {API_KEY}. Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.

Body

application/json

Request body to send a chat message.

​
query
string
required

User input/question content.

​
inputs
object
required

Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the user_input_form field in the Get App Parameters response to discover the variable names and types expected by your app.

​
user
string
required

User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same user value.

​
response_mode
enum<string>

Mode of response return. streaming (recommended) uses SSE. blocking returns after completion (may be interrupted for long processes). Cloudflare timeout is 100 s. When omitted, defaults to blocking behavior.

Available options:
streaming,
blocking
​
conversation_id
string

Conversation ID to continue a conversation. Pass the previous message's conversation_id. To start a new conversation, omit this field or pass an empty string. The response will return a conversation_id — pass it in subsequent messages to continue that conversation.

​
files
object[]

File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via Upload File and use the returned id as upload_file_id with transfer_method: local_file.

​
auto_generate_name
boolean
default:true

Auto-generate conversation title. If false, use the Rename Conversation API with auto_generate: true for async title generation.

​
workflow_id
string

Specify a published workflow version ID to execute. If not provided, the latest published version is used.

Response

Successful 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 ChunkChatEvent objects.
​
event
string

Event type, fixed as message.

​
task_id
string<uuid>

Task ID for request tracking and stop response API.

​
id
string<uuid>

Unique ID of this response event.

​
message_id
string<uuid>

Unique message ID. Use this as the message_id parameter when calling feedback or suggested questions endpoints.

​
conversation_id
string<uuid>

Conversation ID.

​
mode
string

App mode, fixed as advanced-chat.

​
answer
string

Complete response content.

​
metadata
object

Metadata including usage and retriever resources.

​
created_at
integer<int64>

Message creation timestamp (Unix epoch seconds).