desk-ops

A command that ran answers 200 whatever its exit code (exit, remote_code, error), as exec --json prints it; one the desk refused to start answers 200 with exit 254 and a refused error, also as the CLI does. ?stream=1 answers Server-Sent Events instead: stdout, stderr, then exit (or error), each event's data one ExecEvent object, as exec --json-stream prints them. A refusal in the stream's first moments is an HTTP error; a failure after the stream started (the desk's, or the desk lost) is its last event, error, and the call's audit event records that failure, not the 200. Output buffered for a JSON answer is capped at 8 MB (truncated); every call at 15 minutes (timeout_secs defaults to, and is held under, that limit — start a job for longer work). A streamed call is never replayed for an Idempotency-Key.

The desk verifies the credential itself, as for gaiadesk-cli: from an API key, a scoped agent token in X-GaiaDesk-Desk-Token (its scopes, cwd confinement and low-privilege user apply); from a signed-in person, their own account on their own desk. A desk whose owner turned off "Allow commands from the GaiaDesk API" answers 403 desk_opted_out.

Administrator work is NOT available through the API: a body with "admin": true is refused (200, exit 254, error.reason admin_not_via_api) before anything is asked or run. Run administrator work with gaiadesk-cli exec --admin or the SDK's direct transport (docs/admin-access.md).