Skip to main content
POST
/
completion-messages
cURL
curl --request POST \
  --url 'https://{api_base_url}/completion-messages' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --no-buffer \
  --data '{"inputs": {"city": "San Francisco"}, "response_mode": "streaming", "user": "{user}"}'
import requests

url = "https://{api_base_url}/completion-messages"

payload = {
"inputs": { "city": "San Francisco" },
"query": "Translate 'hello' to Spanish.",
"response_mode": "streaming",
"user": "abc-123",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://example.com/logo.png"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
inputs: {city: 'San Francisco'},
query: 'Translate \'hello\' to Spanish.',
response_mode: 'streaming',
user: 'abc-123',
files: [
{
type: 'image',
transfer_method: 'remote_url',
url: 'https://example.com/logo.png'
}
]
})
};

fetch('https://{api_base_url}/completion-messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/completion-messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'inputs' => [
'city' => 'San Francisco'
],
'query' => 'Translate \'hello\' to Spanish.',
'response_mode' => 'streaming',
'user' => 'abc-123',
'files' => [
[
'type' => 'image',
'transfer_method' => 'remote_url',
'url' => 'https://example.com/logo.png'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://{api_base_url}/completion-messages"

payload := strings.NewReader("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"Translate 'hello' to Spanish.\",\n \"response_mode\": \"streaming\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://example.com/logo.png\"\n }\n ]\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://{api_base_url}/completion-messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"Translate 'hello' to Spanish.\",\n \"response_mode\": \"streaming\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://example.com/logo.png\"\n }\n ]\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/completion-messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"Translate 'hello' to Spanish.\",\n \"response_mode\": \"streaming\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://example.com/logo.png\"\n }\n ]\n}"

response = http.request(request)
puts response.read_body
{
  "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

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.

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

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