Everything long-running is a job. Chat, submit, sync and deploy all return a job id
and are polled. Nothing streams over this API.
Poll on a sane interval. One or two seconds is plenty. Job status changes are
driven by workers, not by how often you ask.
A 404 can mean no access. Kosuke does not distinguish "does not exist" from "not
yours", so treat both the same.
Do not assume a sandbox is awake. It pauses when idle. Ask for the preview to start
it, and expect the first request after a pause to be slow.
Respect 402. Out of credits means new work will not start. Retrying does not help
until the workspace has credits again.
Respect 409.JOB_IN_PROGRESS means wait or cancel. JOB_STOPPED means a person
stopped that run deliberately, so do not immediately start another.
Name the workspace when you create things. A key has no active workspace, so
POST /api/projects needs orgId.
Model ids are validated. An unsupported provider:model__effort string is rejected
rather than coerced. Omit the field to inherit the workspace default.
Keys carry full user authority. There are no scopes. Mint one key per automation,
give it an expiry, and revoke it when the automation stops.