Chat and AI connectors

A connector puts a third-party chat widget or AI assistant on a space and can hand that vendor your content as a knowledge source. You pick a provider from the directory, fill in its settings, and switch on the embed, the knowledge connection, or both. If the product you use has no built-in card, you can define your own provider and install it like any other.

Browse the provider directory

GET /orgs/{orgId}/connector-providers

Needs space.read. It returns every provider this organization can install: the built-in ones first, then the custom ones you defined. Each has a source of builtin or custom, the fields an installer must fill in, and whether it offers an embed, a knowledge binding, or both. A custom provider's id in this list is custom:<id>, and that is the providerId you install it by. Install one into a space with POST /orgs/{orgId}/spaces/{spaceId}/connectors (space.update), sending providerId, config, embedEnabled, knowledgeEnabled and optionally knowledgeScopes and appearance.

Define your own provider

When your vendor is not in the directory, describe it. This is a form, not a release.

POST /orgs/{orgId}/custom-chat-providers
{
  "id": "acme-chat",
  "name": "Acme Chat",
  "description": "Support chat from Acme.",
  "icon": "message",
  "docsUrl": "https://acme.example/docs",
  "fields": [
    { "key": "siteId", "label": "Site id", "type": "text", "required": true }
  ],
  "embed": {
    "origin": "https://widget.acme.example",
    "script": "window.AcmeChat = { site: \"{{siteId}}\" };",
    "src": "https://widget.acme.example/loader.js",
    "consent": "functional"
  }
}

Needs org.manage_integrations. The rules the server enforces:

• id is a kebab-case slug of 2 to 60 characters. It cannot match a built-in provider or one of your own (409) and it never changes after creation, because installs point at it. A PUT whose body id differs from the path is a 422.

• A provider must declare an embed, a knowledge binding, or both.

• Up to 12 fields, each of type text, url or password. Field keys are alphanumeric and start with a letter.

• embed.script and embed.src are templates: {{siteId}} is replaced by the installer's value and escaped at render time. They are not pasted JavaScript. embed.consent is functional, analytics or marketing and feeds your consent banner. connectOrigins lists up to 6 hosts the widget talks to once running. A third-party widget runs on custom domains only unless the definition sets platformSafe.

• knowledge says how the vendor consumes your content: the capabilities it asks for, pull for whether it fetches on its own schedule, and an optional register template to tell the vendor about the space in one click.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a CLI command or MCP tool exists too, the last column names it. Operation names link to the API reference.

Connector Providers

Connectors

Custom Providers