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 Exactly one terminal event is emitted per stream, ever. Read the whole
output off
"stream": true and the body becomes text/event-stream. Nothing else
about the request changes.response.completed — see Streaming for why the
deltas are advisory and the completion event is authoritative.5
Look at what it actually did
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
Errors — switch on code, never on message
Errors — switch on code, never on message
message is prose and may be reworded without a version bump. code is a
closed vocabulary of seventeen values. Errors402 and 429 are not failures
402 and 429 are not failures
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.Send an Idempotency-Key on every write
Send an Idempotency-Key on every write
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
Do not build a cursor
Do not build a cursor
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.
