Skip to main content
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 *:write scope includes the matching *:read. A *:write scope on an inference key counts as missing (403 scope_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 /api prefix (/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, plus request_id, retryable, retry_after_seconds and details. Branch on code only.
  • 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 → 409 idempotency_key_conflict; original still running → 409 idempotency_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​

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