Skip to main content

API versions and interface changes

Product endpoints use the /v1 route family. The CLI, SDK and MCP are released together under one version; /v1 does not yet promise a stable interface. While the interface is young, request fields, commands and supported behavior can change without a guaranteed deprecation or sunset notice period. Pin the client release used by an automation, and review the changelog, current release and OpenAPI contract before updating. Only the current release is published; older release URLs return 404, so keep your own copy and checksum of an archive you pin. A pinned client does not freeze the server contract or guarantee that every older client remains compatible.

Request failures

Act on code, suggested_action and retryable; HTTP status only groups error codes. 401: authenticate. 402: credits, Paid access or a Stop budget block the request. 403: the account lacks permission, GitHub lacks repository access, an interactive login is required or Performance needs Paid. 409: a prerequisite must change, such as GitHub connection, sender domain, plan or ETag. An API 429 requires waiting for Retry-After. Repeat an unchanged request only when retryable is true; an uncertain response keeps the original request and idempotency key. Never start another payment or destructive mutation with a new key merely because its result is unknown. Database API reads and writes retain application RLS. Empty results are not proof that no rows exist, and the write count does not include every possible trigger/cascade effect. Use database access for the request and receipt contract. An oversized application result answers non-retryable SQLSTATE 54000: page reads or split writes. query(), transaction() and an autocommit held statement roll back a rejected RETURNING write or WITH statement. Inside your own BEGIN, the effects remain in that open transaction: send ROLLBACK or end the held scope without COMMIT. Input rejected before sending is database_query_invalid; an idle or expired held scope is database_unavailable and needs a new scope. A billing_issue refers to an existing invoice. Follow its address-correction or contact action and preserve that invoice; a new payment or disabled tax is not a retry strategy. Billing issues.

Waiting for work

The original operation is the source of progress. CLI --wait has a bounded local wait; the operation can continue afterward. MCP status tools return current observations. Follow the response’s polling interval and stop on terminal state. For pending mail verification, follow the returned next_check_after_seconds, currently 60 seconds. Custom-domain status returns no interval: check it again after DNS changes have had time to propagate rather than rebuilding. A Skill instruction to poll does not schedule a future agent run. Arrange your harness’s supported scheduler when authorized, or keep the operation ID and return the next command to the user. OpenAPI schemas contain the exact field, request and endpoint limits. Status · Export.