Skip to main content
POST
cURL

Authorizations

​
Authorization
string
header
required

A managed API key, sent as Authorization: Bearer <key>. A workspace key is prefixed tgcc_; a reseller key is prefixed tgpk_. Keys carry scopes; the scope each operation demands is on the operation as x-required-scope.

Headers

​
Idempotency-Key
string

A key of your own choosing, so a retry cannot create a second of anything. Replayable for 24 hours. An unfinished claim is released after 15 minutes, so a request that died mid-flight does not block its own retry.

Maximum string length: 255

Path Parameters

​
agent_id
string
required

Body

application/json

Options may be sent flat in the body or nested under options; both are read and the nested value wins. An unrecognised key inside options is a 400.

The fields below are the complete set a caller may set. These are refused by name with a 400 explaining why, because the caller must not be able to override the runtime's security or billing behaviour:

  • billing_account — Billing is derived from the authenticated tenant.
  • idempotency_key — Send an Idempotency-Key header instead.
  • instructions — Prompt assembly is the runtime's, not the caller's.
  • knowledge_groups — Knowledge scope comes from the agent and the caller's own authorization.
  • max_tokens — Token limits are not caller-controlled.
  • memory_namespace — Memory namespacing is derived from the execution context.
  • model — Model selection is decided by runtime routing.
  • prompt — Prompt assembly is the runtime's, not the caller's.
  • provider — Provider selection is decided by runtime routing.
  • request_id — Request ids are minted by the runtime.
  • system_prompt — Prompt assembly is the runtime's, not the caller's.
  • temperature — Sampling parameters are not caller-controlled.
  • tools — Tool availability comes from the agent configuration.
  • top_p — Sampling parameters are not caller-controlled.
  • trace_id — Trace ids are minted by the runtime.
  • usage_category — Billing is derived from the authenticated tenant.
​
attachments
object[]
​
channel
enum<string>

How the request arrived. "" means "not stated" and falls through to the conversation's own channel — it is not a synonym for api, because the channel decides both rendering and which ledger line the turn bills to.

Available options:
,
api,
web,
website,
whatsapp,
phone,
voice
​
input
​
locale
string
​
metadata
object
​
request_context
object

Caller-supplied context. The one key the runtime acts on is resource_id, which narrows the execution context to that resource — and raises rather than narrowing to nothing when the caller could not reach it.

​
knowledge_policy
enum<string>
default:auto

These three can only ever subtract. There is no value meaning "retrieve more than this agent is configured for".

Available options:
auto,
none,
required
​
memory_policy
enum<string>
default:auto
Available options:
auto,
none
​
preview
boolean
default:false

Run the agent's unpublished configuration (§94). Asking is free; being allowed is not. A machine caller needs the agent:preview scope, which is issued on its own and is not implied by any other — a key that may edit an assistant does not thereby preview its drafts.

Without permission the answer is 404, not 403: confirming that a draft exists but may not be run is the confirmation the not-found rule exists to withhold.

Statuses a preview run may execute: active, draft, paused, preview. Without preview, only active.

​
response_format

Ask for structured output (§31). json_schema validates the model's output against schema and retries a mismatch once before failing with 422 structured_output_failed, which names the paths that did not match. The bound is read before the run starts, so the number of model calls a structured request can cost is knowable in advance.

The schema is checked when the request is parsed — before authorization, before the idempotency claim, and before any spend — so a schema this runtime cannot enforce is a 400 rather than a charge. strict is accepted only as true: there is no mode in which a schema is requested and not enforced.

Available options:
text,
json_object,
json_schema
​
stream
boolean
default:false

Answer with Server-Sent Events rather than one JSON body. The event contract is in this document's description; a failure that happens before the first event is still an ordinary JSON error with its own status code.

​
timeout_ms
integer
default:60000

Out of range is refused, not clamped: a caller who asked for ten minutes and silently got sixty seconds reads the resulting timeout as a platform fault.

Required range: 1000 <= x <= 120000
​
tool_policy
enum<string>
default:auto
Available options:
auto,
none,
required
​
agent
string

The assistant to run. Required by /responses; taken from the URL by /agents/{agent_id}/runs, and from the conversation when posting a message — a body that named a different one there would be a request to run somebody else's assistant on this transcript.

​
external_ref
string

Your own id for a conversation (§46). Resolving the same one twice returns the same conversation rather than a second beside it. Printable, no newlines.

Maximum string length: 200
​
options
object

Options may be sent flat in the body or nested under options; both are read and the nested value wins. An unrecognised key inside options is a 400.

The fields below are the complete set a caller may set. These are refused by name with a 400 explaining why, because the caller must not be able to override the runtime's security or billing behaviour:

  • billing_account — Billing is derived from the authenticated tenant.
  • idempotency_key — Send an Idempotency-Key header instead.
  • instructions — Prompt assembly is the runtime's, not the caller's.
  • knowledge_groups — Knowledge scope comes from the agent and the caller's own authorization.
  • max_tokens — Token limits are not caller-controlled.
  • memory_namespace — Memory namespacing is derived from the execution context.
  • model — Model selection is decided by runtime routing.
  • prompt — Prompt assembly is the runtime's, not the caller's.
  • provider — Provider selection is decided by runtime routing.
  • request_id — Request ids are minted by the runtime.
  • system_prompt — Prompt assembly is the runtime's, not the caller's.
  • temperature — Sampling parameters are not caller-controlled.
  • tools — Tool availability comes from the agent configuration.
  • top_p — Sampling parameters are not caller-controlled.
  • trace_id — Trace ids are minted by the runtime.
  • usage_category — Billing is derived from the authenticated tenant.

Response

The run completed, or ended in a status the response object names. With "stream": true the body is Server-Sent Events instead; see the event contract in this document's description. A failure that happens before the first event is an ordinary JSON error with its own status — the stream only becomes a 200 once a byte is on the wire.

§33's response object. output is an array because a run can produce more than one thing — prose plus a structured object, or a refusal — and a contract that starts as a string has nowhere to put the second one.

​
agent
string
​
agent_version
integer
​
conversation
string

Omitted by POST /api/v2/responses, which is stateless: it opens an internal conversation so the turn has somewhere to live, writes no messages to it, and returns no id.

​
id
string

The public run id, run_…. Database primary keys are never exposed.

​
metadata
object
​
output
object[]
​
request_id
string
​
status
enum<string>
Available options:
queued,
running,
completed,
failed,
cancelled,
blocked
​
trace_id
string
​
usage
object