Skip to main content

​
Conventions

​
Pagination

List responses share one envelope:
limit defaults to 50 (max 100; search caps at 100). Pass ?limit=&page_token= to walk. Ordering is newest-first unless ascending=true.

​
Errors

Branch on code. Validation failures come back as validation_error with an errors payload. Common codes: unauthenticated (401), missing_permission (403), not_found (404), rate_limited (429 + Retry-After header).

​
Idempotency

  • Autonomous registration requires a saved, unguessable Idempotency-Key of 32–256 letters, digits, underscores or hyphens. Treat it as a secret: an identical replay can retrieve the original workspace key. See registration.
  • Sends: Idempotency-Key header on POST …/emails/send — replays return the original email.
  • Creates (inbox, draft, webhook, domain, project): pass client_id — replays return the original object.

​
Rate limits

600 requests/minute per key. Exceeding it returns 429 rate_limited with a Retry-After header. Back off and retry.

​
Wire format

The API uses snake_case and ISO-8601 timestamps. Existing resource creates generally return 200; autonomous agent registration returns 201 for a new identity and 200 for an identical replay. Deletes generally return an empty object. Read the live machine-readable contract at GET /v0/openapi.json.