Send Completion Message

Available for: Text Generator apps.

Sends a request to a text-generation app and returns the generated text.

POST /completion-messages

cURL

blocking_example

curl --request POST \
  --url https://{api_base_url}/completion-messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {
    "city": "New York"
  },
  "query": "Summarize the following text: ...",
  "response_mode": "blocking",
  "user": "def-456"
}
'

200

blockingResponse

{
  "answer": "Hello World!...",
  "created_at": 1705407629,
  "event": "message",
  "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
  "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "metadata": {
    "usage": {
      "completion_price": "0.0002560",
      "completion_price_unit": "0.001",
      "completion_tokens": 128,
      "completion_unit_price": "0.002",
      "currency": "USD",
      "latency": 0.7682376249867957,
      "prompt_price": "0.0010330",
      "prompt_price_unit": "0.001",
      "prompt_tokens": 1033,
      "prompt_unit_price": "0.001",
      "total_price": "0.0012890",
      "total_tokens": 1161
    }
  },
  "mode": "completion",
  "task_id": "c3800678-a077-43df-a102-53f23ed20b88"
}

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

Body

application/json

Request body to create a completion message.

inputs · object · required

Values for the app's input variables, keyed by variable name. The expected names and types come from the user_input_form field of Get App Parameters.

user · string · required

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

files · object[]

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

Option 1

Option 2

Show child attributes

query · string · default: ""

The text to process. Legacy field; newer apps pass this inside inputs instead.

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

Response

200

application/json

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.

answer · string

Complete response content.

created_at · integer<int64>

Message creation timestamp (Unix epoch seconds).

event · string

Event type, fixed as message.

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.

metadata · object

Metadata including usage and retriever resources.

Show child attributes

mode · string

App mode, fixed as completion.

task_id · string<uuid>

Task ID for request tracking and the Stop Completion Message Generation API.