Skip to main content
POST
/
api
/
v1
/
engine
/
executions
/
{executionId}
/
resume
Error
A valid request URL is required to generate request examples
{
  "execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "blocks": [
    {
      "type": "<string>",
      "id": "<string>",
      "payload": {},
      "meta": {}
    }
  ],
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expected_input": {},
  "metadata": {},
  "token_usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1,
    "model": "<string>",
    "cost_micros": 1,
    "cost_usd": 123
  }
}

Authorizations

​
Authorization
string
header
required

Deploy-wide server-to-server bearer token (ENGINE_API_TOKEN), validated by the engine_api firewall. Authenticates the Engine API, Knowledge base, and Conversions surfaces. The tenant_id rides in the request body and is trusted in V1 — keep this token strictly server-side.

Headers

​
Idempotency-Key
string

Make the call safe to retry. A repeat with the same key returns the cached response (24h TTL); reusing the key with a different payload returns 409 idempotency_conflict.

Path Parameters

​
executionId
string<uuid>
required

Body

application/json
​
tenant_id
string<uuid>
required
​
wait_token
string
required

From the previous envelope's metadata.wait_token.

​
input
object

Collected input for the paused step (e.g. a values object).

​
context
object
​
variables
object

Optional conversation variables merged into the conversation row and surfaced to the flow as untrusted input. Constraints (rejected with a 422 validation_failed on the chat surface, 422 invalid_input on the Engine API):

  • at most 50 keys;
  • at most 4096 bytes total when JSON-encoded;
  • keys are snake_case matching ^[a-z][a-z0-9_]{0,63}$;
  • values are scalar, null, or arrays nested at most 4 levels deep (plain objects/maps as values are rejected).
Example:
{
  "cart_total": 129,
  "page_path": "/pricing",
  "tags": ["returning", "vip"]
}

Response

Execution envelope

The standard execution envelope returned by every Engine API call that touches an execution — trigger and resume share one parser. Keys are snake_case (the public Chat API uses the camelCase ChatReply shape).

​
execution_id
string<uuid>
required
​
status
enum<string>
required
Available options:
waiting_input,
waiting_time,
completed,
failed,
aborted
​
blocks
object[]
required
​
conversation_id
string<uuid> | null
​
expected_input
object

What to send to /resume next; null when the execution is terminal.

​
metadata
object

metadata.wait_token binds future /resume calls to this exact pause.

​
token_usage
object

Token usage for the turn that produced these blocks, or null.