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
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. Scopes data access: a workflow run and its files are only visible to later requests that carry 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
files
object[] | null

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

The workflow's own file settings decide what is accepted, such as the allowed types and how many files. A workflow that accepts no files ignores these entries.

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 WorkflowBlockingResponse object.
  • If response_mode is streaming, returns text/event-stream with a stream of ChunkWorkflowEvent objects.
task_id
string<uuid>

Task ID for this run. In blocking mode it arrives only in this final body, so Stop Workflow Task is practical only with streaming.

workflow_run_id
string<uuid>

The workflow run's ID.

data
object