Version: 1
Integrations API
Platform integrations: signed webhooks for platform events, and verified domains that prove your organization controls a site. Connections to documentation platforms are not available yet.
Authentication. Authorization: Bearer <API key>.
- Reading (
webhooks:read,domains:read) works with an inference or a management key. - Creating and managing (
webhooks:write,domains:write) needs a management key. A*:writescope includes the matching*:read. A*:writescope on an inference key counts as missing (403scope_missing). - Only an organization owner or admin can give a key these scopes. In the portal (Settings → Integrations) only owners and admins see the pages.
- Each operation lists the scope it needs.
Conventions.
- Paths are also accepted with an
/apiprefix (/api/v1/webhooks). - Ids are lower-case hyphenated UUIDs. Timestamps are RFC 3339 UTC.
- Lists are cursor-paginated:
?limit=(1–100, default 20) and?after=<next_cursor>; responses are{"object":"list","data":[…],"has_more":bool,"next_cursor":string|null}. - Errors use the platform error envelope with a stable
code, plusrequest_id,retryable,retry_after_secondsanddetails. Branch oncodeonly. - A resource of another organization answers exactly like a missing one
(404
not_found). - Adding a domain, checking a domain and sending a delivery again accept
Idempotency-Key(≤255 characters, kept 24 h). Same key and same request → the original response is replayed. Same key with a different request → 409idempotency_key_conflict; original still running → 409idempotency_in_progress. Other calls take no key: creating a webhook and rotating its secret never replay (the plaintext secret in their response is not kept), and each test event is a new send. - Signing secrets are shown once, at creation or rotation. Afterwards only
their last four characters (
secret_hint) are returned.
Authentication
- HTTP: Bearer Auth
API key (sk-…): *:read scopes on an inference or a management key, *:write scopes on a management key only. Or a portal session of an organization owner or admin.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |