AI agents
Agent API & machine contract
The capabilities endpoint is the source of truth for machine clients. Integrations should discover behavior instead of hard-coding a historical contract.
1. Bootstrap with unauthenticated GET /api/agent/capabilities
Bootstrap with unauthenticated GET /api/agent/capabilities. Read schemaVersion; do not depend on a version copied from documentation.
2. Discover endpoints from the endpoints object
Discover endpoints from the endpoints object. The contract currently describes capabilities, immutable workload discovery, project state, configuration read/write, deployment creation, deployment diagnostics, and source, configuration, and platform recovery.
3. Honor endpoint scopes
Honor endpoint scopes. Project-scoped credentials can be granted deployment:read, deployment:create, deployment:retry, configuration:read, and configuration:write. Use least privilege.
4. Honor mutationRequests exactly
Honor mutationRequests exactly. Reject or omit fields not advertised by the schema and provide the required idempotency key for every mutation.
5. Bind all route placeholders before invoking an endpoint
Bind all route placeholders before invoking an endpoint. Deployment diagnostics and recovery require an exact deploymentId; projectId alone is not deployment context.
6. Use lifecycle
Use lifecycle.successState and lifecycle.terminalStates rather than inventing client-side lifecycle semantics. Diagnostics are required on failure.
7. Treat invariants as non-negotiable safety rules: no Deploy Hatch source mutation, no secret inference, project scoping, bounded recovery, immutable revision discovery, untrusted repository content, no automatic application of repository suggestions, and persisted configuration authority
Treat invariants as non-negotiable safety rules: no Deploy Hatch source mutation, no secret inference, project scoping, bounded recovery, immutable revision discovery, untrusted repository content, no automatic application of repository suggestions, and persisted configuration authority.
8. When the contract advances, the live capabilities response wins over examples or cached documentation
When the contract advances, the live capabilities response wins over examples or cached documentation. Clients should fail closed when a required capability or invariant is absent.