Platform Integrations
Integrations connect your organization to the outside world. They belong to the platform, not to one product: knowledge bases are the first product to use them, and other products will use the same webhooks, domains and connections. Knowledge bases are moving their webhooks and domain verification here; see the notes on Knowledge Webhooks and Website Sources.
| Page | Use it to |
|---|---|
| Webhooks | Get a signed POST on your server when something happens, for example when a document is ready |
| Domains | Prove that your organization controls a domain, for example to index your own website with higher limits |
| Connections | Connect a documentation platform once and use it in your knowledge bases. Not available yet |
| Integrations API Reference | Every endpoint and schema |
In the portal, open Settings → Integrations. It has three tabs: Webhooks, Domains and Connections.
Who can manage integrations
Integrations are shared by the whole organization.
- Portal: only owners and admins see and change them. Other members get
403 role_insufficient. - API keys: reading and managing need different scopes, and managing needs a management key.
| Scope | Allows | Key type |
|---|---|---|
webhooks:read | List endpoints, deliveries and event types | Inference or management |
webhooks:write | Everything webhooks:read allows, plus add, change, delete, test, redeliver and rotate secrets | Management only |
domains:read | List domains and their verification state | Inference or management |
domains:write | Everything domains:read allows, plus add, check and delete | Management only |
connections:read | List connections (not available yet) | Inference or management |
connections:write | Add, check, change and delete connections (not available yet) | Management only |
- A key gets these scopes only when you ask for them. No default scope set and no older scope name includes them.
- Only an organization owner or admin can add them to a key.
- A
*:writescope on an inference key counts as missing: the call answers403 scope_missing. - Using an integration needs no integration scope. For example, a knowledge source that uses a verified domain needs only
knowledge:write, on any key type the knowledge API accepts. - An API key limited to a list of knowledge bases cannot read or manage webhooks (
403 kb_not_in_allowlist). A webhook is organization-wide and could carry events of other knowledge bases. Domains and connections are not affected by the list.
See API Keys for key types.
When an area is switched off
Your platform operator can switch webhooks, domains or connections off for the whole platform or for your organization.
- Creating new things and starting new work (add an endpoint, send a test event, check a domain) are refused with
403 integrations_disabled.details.areanames the area.details.scopeisplatformortenant(only your organization). - You can still list and read everything and delete what you have. Webhook endpoints can still be changed (also turned on or off) and their secrets rotated. Connections can only be renamed: a new credential is refused too.
To find out before you try, read GET /v1/integrations/availability. It answers whether each area is switched on for the platform, as booleans only:
{ "object": "integrations_availability", "connections": false, "webhooks": true, "domains": true }
Any one of connections:read, webhooks:read or domains:read lets an API key read it (inference or management key), and so does a portal session of an owner or admin. It is not limited by a key's knowledge-base list. The portal uses it to hide Add on Settings → Integrations while an area is off and shows a notice instead. A create can still be refused with 403 integrations_disabled: the switch can change between the read and the create, and an area can also be off for your organization only, so keep handling that error. Ignore keys you do not know; a new area is a new boolean.
Errors
Every error uses the platform error envelope with a stable code. Branch on code, not on the message.
| Code | Status | Meaning |
|---|---|---|
scope_missing | 403 | The key lacks the scope (details.required_scope), or it is a *:write scope on an inference key |
role_insufficient | 403 | The portal user is not an owner or admin |
kb_not_in_allowlist | 403 | Webhooks with a key limited to a list of knowledge bases |
integrations_disabled | 403 | The area is switched off (details.area, details.scope) |
not_found | 404 | The resource does not exist or belongs to another organization |
validation_failed | 422 | A field is invalid (param names it) |
idempotency_key_conflict | 409 | The Idempotency-Key was used with a different request |
idempotency_in_progress | 409 | The first request with this Idempotency-Key is still running |
rate_limited | 429 | Too many requests; wait retry_after_seconds |