Skip to main content
1

Get a key with the scopes you need

An operator issues a workspace key (tgcc_…). For this page it needs responses:create. The secret is shown once, at creation.
2

Ask an agent for something

POST /responses is stateless from your side. No conversation is named and none comes back — the request leaves a record that it happened and what it cost, and no copy of what was said.
3

Read the response

output is an array, not a string. 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. Item types are text, json and refusal.Quote request_id in a support ticket. It is also on the X-Request-Id response header, including on responses that carry no body.
4

Stream the same call

Set "stream": true and the body becomes text/event-stream. Nothing else about the request changes.
Exactly one terminal event is emitted per stream, ever. Read the whole output off response.completed — see Streaming for why the deltas are advisory and the completion event is authoritative.
5

Look at what it actually did

Needs logs:read. You get status, latency, model, tokens, tool names and error code — the shape of the execution. Prompt assembly and identity steps do not appear at all.

Handle four things and you have a working client

message is prose and may be reworded without a version bump. code is a closed vocabulary of seventeen values. Errors
usage_blocked (402) and rate_limited (429) end a run as blocked, not failed. Retrying a 402 will never help; retrying a 429 after a delay will.
Same key and same body replays the stored response including its status. Same key and a different body is a 409, never a replay. The window is 24 hours. Idempotency
Cursors are opaque base64url. A raw ISO timestamp is not a cursor: +00:00 decodes to a space in a query string, which silently breaks every second page.

Where to go next

Durable conversations

When you want a transcript rather than a one-shot answer.

Structured outputs

Get JSON that validates against your schema, or a 422 that says why not.

Documents and extractions

Upload a file, then pull validated fields out of it with evidence.

Async jobs

What a 202 means, and how to poll it without writing a while True.