Skip to main content
POST
/
completion-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",
  "mode": "completion",
  "answer": "Hello World!...",
  "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
    }
  },
  "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 create a completion message.

​
inputs
object
required

Allows the entry of various variable values defined by the App. Contains key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. 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 — messages and files are only visible when queried with the same user value.

​
query
string
default:""

The input text to be processed. This is a legacy parameter; in newer apps, the query should be passed inside the inputs object.

​
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
​
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.

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 CompletionResponse object.
  • If response_mode is streaming, returns text/event-stream with a stream of ChunkCompletionEvent objects.
​
event
string

Event type, fixed as message.

​
task_id
string<uuid>

Task ID for request tracking and the Stop Completion Message Generation 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.

​
mode
string

App mode, fixed as completion.

​
answer
string

Complete response content.

​
metadata
object

Metadata including usage and retriever resources.

​
created_at
integer<int64>

Message creation timestamp (Unix epoch seconds).