VendorLogic
Request access

Docs / Connectors

Connector documentation contract

How a connector publishes its own docs, how core fetches and caches them, and who can read them.

A connector owns its documentation the way it owns its UI and database. Core does not copy the markdown into its repository or database. It stores one URL and fetches the pages when someone reads them.

What a connector publishes#

  1. A folder of markdown files, for example integrations/<slug>/docs/*.md. The file name is the slug ([a-z0-9-]+).
  2. Front matter on each file, the same schema as the core docs (title, summary, order, personas, updated) without section or audience, which core decides. personas defaults to supplier.
  3. An index at GET <base>/docs/index.json: an array of { slug, title, summary, order, personas, updated? }, and each page at GET <base>/docs/<slug>.md. Both are public and unauthenticated, so they must hold no customer data.
  4. The URL of the index in the manifest: docs: { url: "https://<host>/official-integrations/<slug>/docs/index.json" }.

The SDK does the serving: loadDocs(dir) reads and validates the folder (a bad file fails at start, not in front of a customer) and serveDocs(docs, path) answers both routes. pnpm docs:check validates integrations/*/docs/*.md with the same schema and checks relative links.

What core does#

RouteWhoResult
GET /v1/connect/docssigned in[{ slug, name, publisher, pages }] for connectors the caller's organization has installed; staff get every connector with docs; anyone else gets []
GET /v1/connect/docs/:slug/:pagesigned in{ markdown } for a page listed in the connector's index; 404 for anything else, including a connector the organization did not install
  • Visibility is decided from the database on every request. Uninstalling removes the docs at once; installing shows them at once.
  • Fetches time out after 4 seconds, refuse redirects and accept at most 200 KB. The answer is cached for 60 seconds per URL in the services process. If the connector is down, its last good copy is served for that window and then its docs are simply missing. Nothing else breaks.
  • The docs URL is fetched through the SSRF guard: a URL that resolves to a private, loopback or link-local address is refused (the connector's docs go missing) unless its hostname is listed in OUTBOUND_ALLOW_PRIVATE_HOSTS.
  • Only pages named in the index are fetched. The page name from the caller is never used to build an arbitrary URL.

What readers see#

The docs site shows these pages under Connectors, with a "Provided by <connector>" line, and the page text is rendered as markdown with raw HTML ignored. Links inside a connector's page that are not http or https are dropped.

Core vouches for where a page came from, not for what it says. The connector's publisher is responsible for the content.

  • Writing docs