Skip to main content

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.

PageUse it to
WebhooksGet a signed POST on your server when something happens, for example when a document is ready
DomainsProve that your organization controls a domain, for example to index your own website with higher limits
ConnectionsConnect a documentation platform once and use it in your knowledge bases. Not available yet
Integrations API ReferenceEvery 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.
ScopeAllowsKey type
webhooks:readList endpoints, deliveries and event typesInference or management
webhooks:writeEverything webhooks:read allows, plus add, change, delete, test, redeliver and rotate secretsManagement only
domains:readList domains and their verification stateInference or management
domains:writeEverything domains:read allows, plus add, check and deleteManagement only
connections:readList connections (not available yet)Inference or management
connections:writeAdd, 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 *:write scope on an inference key counts as missing: the call answers 403 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.area names the area. details.scope is platform or tenant (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.

CodeStatusMeaning
scope_missing403The key lacks the scope (details.required_scope), or it is a *:write scope on an inference key
role_insufficient403The portal user is not an owner or admin
kb_not_in_allowlist403Webhooks with a key limited to a list of knowledge bases
integrations_disabled403The area is switched off (details.area, details.scope)
not_found404The resource does not exist or belongs to another organization
validation_failed422A field is invalid (param names it)
idempotency_key_conflict409The Idempotency-Key was used with a different request
idempotency_in_progress409The first request with this Idempotency-Key is still running
rate_limited429Too many requests; wait retry_after_seconds

Codes of one area are on its page: Webhooks, Domains.