Integrations

Connect Notion

Embed and update spec pages in your Notion workspace.

Updated

The Notion integration lets you publish a human-readable rendering of your spec into a Notion page — useful when stakeholders live in Notion and you want them to see the latest API surface without leaving.

Connecting

From workspace settings → Integrations, click Connect next to Notion. Approve the scopes:

  • read_content
  • update_content
  • insert_content

You’ll be asked to share the specific pages with the OpenAPI Studio integration in Notion’s permission UI — Notion only exposes pages you explicitly share, even after OAuth. Pick the parent page where spec docs should live (or create a fresh one).

Publishing a spec

  1. Open the spec.
  2. Export panel → Notion → Publish.
  3. Pick the parent page.
  4. Click Publish.

We create a Notion page named after the spec, with structured sections per tag and per operation: summary, description, parameters table, request body example, response codes.

Updating

Open the same spec → Notion → Update. Existing sections are diff-updated (no full overwrite that would break inline comments). Operations removed from the spec are deleted from Notion; new operations are appended.

Linking

Notion pages get a small “Live in OpenAPI Studio” link at the top that deep-links back to the editor — handy for the engineer who reads the doc and wants to test the endpoint.

Limits

  • Up to 500 operations per spec to fit Notion’s block limits.
  • Update runs are one-at-a-time per spec; concurrent updates are queued.

Disconnecting

Workspace settings → Integrations → Notion → Disconnect. The token is revoked. Notion pages already published remain — Notion considers them yours.