OpenAPI
OpenAPI describes an HTTP API in a machine-readable document: paths, methods, parameters, schemas, responses and security. Connect publishes one at /developers/openapi.yaml, written to 3.1.0, covering the public documentation API only. The application's own generated document stays closed.
What the document actually contains#
An OpenAPI description is a contract, not documentation prose. Each path carries the operations available on it, each operation carries its parameters and request body, and each response carries a schema. Because 3.1.0 aligns with JSON Schema, those schemas are the same objects you would validate against anywhere else rather than a near-miss dialect — which is the change that made 3.1 worth adopting in the first place.
What a client gets from it is concrete: generated types, request validation before the network call, a browsable reference, and mock servers for tests. What a *server* gets is a place where a change to the shape of an endpoint is visible in a diff.
| Path | What it does |
|---|---|
/api/public/docs/search | Search the published corpus |
/api/public/docs/page | Fetch one page by id or URL |
/api/public/docs/list | List pages by kind, status, channel or audience |
/api/public/docs/status | The capability status manifest |
/api/health | Liveness |
Why 3.1.0 and not the newer revision#
A 3.2.0 revision exists. Connect's description is written to 3.1.0 anyway, for a reason that is about tooling rather than about the specification: support for 3.1 is universal across generators, linters and documentation renderers, and nothing in this API needs a feature that only 3.2 provides. Publishing a version that some readers' tooling cannot load would cost real usability to gain nothing.
That is the general rule worth taking away. The newest revision of a description format is worth adopting when you need something in it, and not before — a description exists to be read by other people's tools.
A public contract is not an internal route map#
Most web frameworks can generate an OpenAPI document from the routes they are running. That generated document describes the *application*: every endpoint, including the operator ones, the internal ones, and the ones added last week. Serving it publicly turns an implementation detail into a published interface and hands an attacker a map.
Connect keeps the two apart. The application's own /openapi.json, /docs and /redoc are closed and stay closed. The published description is generated from an allowlist: a route appears in it because it is named in the generator's public-route list, so opening a new internal endpoint cannot publish it by accident.
- Internal route map
- Every route the app serves. Changes on every release. Useful to the team, dangerous in public.
- Public contract
- The routes deliberately promised to outsiders. Changes only when the promise changes. This is what versioning, deprecation and support apply to.
Does Connect use OpenAPI?#
Yes, as a publisher. /developers/openapi.yaml is generated by the documentation build from the same registry the pages come from, so the description and the prose cannot disagree. It is regenerated on every build and is not edited by hand.
Its scope is narrow and stated in the file itself: everything described is public and unauthenticated, and workspace data is not reachable through it. Reading a business's mail, calls or contacts needs a signed-in session, or an integration key on a separate surface — see API authentication.
Connect does not consume other people's OpenAPI documents at runtime. Provider integrations — mail, telephony, messaging — are written against each provider's own client, not generated from a description fetched on the fly.
Questions#
Can I generate a client from Connect's description?
Yes — that is what it is for. Any generator that reads OpenAPI 3.1.0 will produce a client for the five public paths. Pin the version you generated from; see API versioning for how changes are signalled.
Why can I not see Swagger UI on the application?
Because it is switched off, along with /openapi.json and /redoc. Those surfaces describe every internal route, which is not something to publish. The written description at /developers/openapi.yaml is the public equivalent and is deliberately much smaller.