Execute an agent

/v1/agents/{id}/execute

Send prompt (or its alias input). The spec marks neither as required, but the handler answers 400 missing_prompt without one.

Headers: every response carries x-request-id (quote it in support requests). Send x-trace-id (optional, a UUID) to correlate this call across planes; reusing an id that already ran answers 409 duplicate_execution_id. Pick the body format with format or Accept (application/json, text/yaml, text/markdown, text/plain).

Authorization: send Authorization: Bearer $PLUNGE_API_KEY; X-API-Key: <ozk_ key> is accepted as an alternative.

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer ozk_…. ozk_ platform API key (Authorization: Bearer ozk_…)

Path parameters

idstringrequired

Body

application/json

promptstring

inputstring

Alias for prompt

personastring

providerstring

Provider id (anthropic, openai, gemini, …); required alongside a pinned model

modelstring

maxTokensinteger

Max output tokens (alias: max_tokens)

max_tokensinteger

Alias for maxTokens

temperaturenumber

Sampling temperature, forwarded to the provider

top_pnumber

Nucleus sampling probability, forwarded to the provider

reasoning_effortstring

Reasoning-effort hint (e.g. low/medium/high) for reasoning models

thinking_levelstring

Extended-thinking level hint for models that support it

systemstring

System prompt / instructions for the run

messagesobject[]

Prior chat messages ([{role, content}]) instead of a single prompt

syncboolean

Default: true

streamboolean

When true, the response is an OpenAI-shaped chat.completion.chunk SSE (see the 200 text/event-stream variant) instead of a JSON result. Ignored by the async pointer path.

Default: false

formatenum<string>

Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format.

Available options: json, yaml, markdown, text

Response

Resolved result. Default (stream absent/false): a JSON result object. With stream:true: an OpenAI-shaped chat.completion.chunk SSE — one primer chunk carrying delta.role="assistant", then a delta.content chunk per provider token, then a final chunk with delta:{} and finish_reason "stop" (or "length" when the model was truncated at max_tokens), then a literal data: [DONE] line. usage is emitted on the final chunk only when the provider reports the prompt/completion split (often omitted for streamed runs). Comment keepalives (: OCEAN PROCESSING) may appear every ~15s while idle. Errors before the first byte are the normal JSON error envelopes below (not SSE); an error after the first byte is a single data: {"error":{…}} frame and the stream closes WITHOUT [DONE]. Response header X-Execution-Id carries the execution id for result redemption / polling. Response format negotiates via the format field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.

application/json
text/yaml
text/markdown
text/plain
text/event-stream

Response headers

x-request-idstringfrom code

Server-minted request id.

X-Execution-Idstringfrom code

The execution this call opened.

contentstringrequired

workflow_idstring

task_idstring

request_idstring

Accepted (async) — redeem via /v1/agents/results/{workflowId}/{taskId}

application/json

workflow_idstring

task_idstring

request_idstring

missing_prompt / invalid_format — format must be one of json, yaml, markdown, text

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

Missing, invalid, expired or revoked ozk_ key.

Error code: unauthorizedfrom code

agent_not_active — the agent card is not status:active (refused pre-dispatch)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

unknown_agent — no such agent id in the registry (refused pre-dispatch)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

duplicate_execution_id — x-trace-id already used by an earlier run — send a fresh UUID

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

invalid_params — needs_input (the agent named a missing/invalid input); unknown_model (pinned model absent/inactive in the catalog); empty_completion (the run completed but the model returned no visible content — raise max_tokens ≥ 64 or change the model)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connection_required / credential_required — agent needs a connection or key

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

rate_limited — Retry-After header

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

engine_error / result_unavailable

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

agent_unavailable — agent temporarily down

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

Stream events

Event	Description
`chat.completion.chunk (role)`	The first chunk opens the assistant message.
`chat.completion.chunk (content)`	One content delta.
`chat.completion.chunk (stop)`	The last chunk carries `finish_reason` and `usage`.
`[DONE]`	End of the stream.

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"pong"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":72,"completion_tokens":1,"total_tokens":73}}

data: [DONE]

Authorizations

Path parameters

Body

Response

Response headers

Stream events

Planned: TI-33

Planned: TI-34