Create pages and navigation
A useful developer portal is more than an endpoint list. Organize pages around the work a client is trying to finish, then let OpenAPI power the exact contract details.
Begin with the client journey
For most APIs, start with:
- Overview — outcome, audience, and important constraints.
- Quickstart — credentials, base URL, and one successful request.
- Core concepts — the domain model and lifecycle clients must understand.
- Guides — complete tasks that combine several endpoints.
- API reference — operations and schemas generated from OpenAPI.
- Errors and limits — error shape, retries, idempotency, pagination, and rate limits.
- Changelog and support — breaking changes, version policy, and contact.
Create a page
Open a portal, add a page, give it a short title and stable slug, then add blocks. A page can be visible to anyone or restricted to authenticated members.
Avoid changing a shared page slug: links from clients and search results may depend on it.
Choose the right block
| Need | Block |
|---|---|
| Explanations, headings, lists, tables | markdown |
| A warning, prerequisite, or result | callout |
| A copyable command or payload | code |
| Equivalent examples by language | tabs |
| A set of guide choices | card_grid |
| A single OpenAPI operation | endpoint |
| One reusable data model | schema |
| An index of operations | endpoint_list |
| A visual separator | divider |
Spec-driven blocks require an attached spec_file. Their operation address is
either op:<operationId> or op:<METHOD> <path>; schema addresses use
schema:<Name>. Export a generated portal to see exact working addresses.
Build navigation
Navigation has four levels:
Top bar links
└── Tab
└── Group
└── Page or external link
Use tabs only for genuinely distinct areas, such as Guides and API Reference. Use groups for scannable sections inside a tab. A page may be hidden from navigation while remaining reachable by its direct URL.
Top-bar links are best for status, support, dashboard, or another destination outside the documentation. Portal search can also be enabled in the top bar.
Write a quickstart that proves success
A quickstart should let a new client confirm the integration, not explain every feature. Include:
- How to get credentials.
- Which environment and base URL to use.
- One complete command with safe placeholders.
- The expected successful response.
- The most likely error and its fix.
- A link to the next useful task.
Gate internal pages
Set visible_to to authenticated for runbooks, internal schemas, or partner
material that only workspace members should read. A public portal may contain a
mix of public and authenticated pages.
Test restricted pages in a signed-out browser. Navigation hiding alone is not access control; the page gate must enforce authentication.
Use portal JSON for repeatable structures
Open Settings → General → Export JSON to capture pages, blocks, theme, and navigation. You can review or generate the document, then import it as a new portal from Portals → Import JSON.
Continue with the portal JSON guide or use the complete component reference.