API FLEETDocs

Build your first developer portal

This guide starts with a repository containing an OpenAPI document and ends with a branded, access-controlled portal that clients can use. You can also follow it with a local YAML or JSON file by using Paste a spec.

What you need

  • An API Fleet account and workspace.
  • A valid OpenAPI 3.x file in YAML or JSON.
  • For repository sync: permission to install the API Fleet GitHub App on the selected repository.
  • For a custom domain: permission to add DNS records for that hostname.

Keep secrets and real customer data out of examples. An OpenAPI document is documentation, not a secure place for credentials.

1. Create or choose a workspace

Sign in, complete onboarding, and create your organization. The active workspace determines who can see connected specs, portals, and builds. You can switch organizations from the workspace control in the sidebar.

Invite collaborators later from Members. Give each person the least powerful role they need.

2. Connect an OpenAPI document

Choose one source of truth.

Option A: sync from GitHub

  1. Open GitHub Sync in the sidebar.
  2. Install or connect the API Fleet GitHub App.
  3. Select the repository and branch.
  4. Enter the file pattern that matches your specs, for example openapi/**/*.yaml.
  5. Save the connection, then choose Sync now.
  6. Wait for the sync job to finish and review the discovered files under Connected specs.

The background worker reads matching files from the selected commit. A later sync updates the stored draft spec and records the new source commit. It does not silently replace an already-published portal build.

Option B: paste YAML or JSON

  1. Open Connected specs.
  2. Choose Paste a spec.
  3. Give the file a recognizable name such as payments.yaml.
  4. Paste the complete OpenAPI document and save it.

Use paste for evaluation and one-off specs. Repository sync is the more reliable source for a team because changes remain reviewable in Git.

3. Check the spec before generating

Confirm the spec appears under Connected specs and inspect the title, version, operations, tags, and schemas. Fix parsing errors at the source, then sync or paste again.

Good portal output starts with useful summaries, descriptions, operation IDs, examples, response bodies, and schemas. API Fleet can arrange missing content; it cannot invent a contract clients should trust.

4. Generate the portal

From Connected specs, choose Generate portal for the spec. You can also open Portals, choose New portal, and start blank when you want a guide- first portal.

Give the portal a client-facing name. Generation creates editable pages and spec-driven endpoint blocks. It does not publish anything.

5. Build the information architecture

Start with the smallest structure that answers a client's first questions:

  1. Overview — what the API does and who it is for.
  2. Quickstart — authentication, base URL, and one successful request.
  3. Concepts — the few domain ideas required to use the API correctly.
  4. API reference — operations, parameters, request bodies, responses, and schemas sourced from OpenAPI.
  5. Errors and limits — error shape, status codes, idempotency, pagination, and rate limits.
  6. Changelog or support — how clients learn about changes and get help.

Use navigation tabs and groups for user tasks, not for your internal service names. Keep page slugs stable after sharing links.

6. Add content blocks

Use Markdown for explanations and native blocks for structured interactions:

  • callout for warnings, prerequisites, and successful outcomes.
  • code for copyable commands or payloads.
  • tabs for equivalent examples in several languages.
  • card_grid for paths through a guide.
  • endpoint, schema, and endpoint_list for content bound to a connected OpenAPI file.

For a repeatable or reviewable setup, export or author the entire portal using the portal JSON format. The component reference lists every supported field.

7. Apply the visual system

Open the portal theme controls and set the logo, brand colors, typography, width, density, and light/dark behavior. Prefer theme tokens because they are validated and stay coherent across components.

Use theme.custom_css only for trusted, advanced styling. It is global to the portal and may load external assets. Read the customization guide before relying on CSS selectors.

8. Configure access

Open Settings → Access and choose the portal state:

  • Draft — editable and not available as a public live portal.
  • Preview — inspect the candidate build before making it the live version.
  • Live — serve the currently published build.

Pages can be visible to anyone or only authenticated workspace members. Test both an anonymous browser and a signed-in account before sharing the URL.

9. Add a custom domain

Open Settings → Custom domain, enter a hostname such as docs.company.com, and copy the verification records exactly. API Fleet must verify control of the hostname and provision TLS before it can serve traffic.

After verification, add the CNAME shown by API Fleet at your DNS provider. Do not use a web redirect: DNS must route the hostname to the portal edge so HTTPS and every documentation path continue to work.

DNS and certificate changes can take time to propagate. Keep the API Fleet hostname available until the custom domain shows as verified and serves HTTPS.

10. Preview and publish

Preview the portal at desktop and mobile sizes. Check navigation, search, authentication, code copy, examples, external links, and the first API request.

When ready, publish. API Fleet creates an immutable build snapshot and marks it live. If the connected spec later syncs to a newer commit, the draft and live versions will differ until you review and publish again.

11. Roll back safely

Open Settings → Publishing to see build history. Each row represents a previous snapshot. Preview the intended version, then choose Restore. A restore changes the selected live build; it does not erase history.

12. Export a portable backup

Open Settings → General → Export JSON. Keep the file in a private or reviewed repository. It contains portal structure and theme configuration, but referenced specs must already exist in the destination workspace before an import can succeed.

Launch checklist

  • [ ] A new client can reach one successful request from the Quickstart.
  • [ ] Authentication, base URLs, errors, pagination, and rate limits are clear.
  • [ ] Every endpoint block points to the intended spec and operation.
  • [ ] Anonymous and authenticated page gates behave as expected.
  • [ ] Search returns useful results for product vocabulary.
  • [ ] Logo, favicon, domain, and TLS are correct.
  • [ ] External links and code examples work.
  • [ ] The live build matches the approved preview.
  • [ ] A portal JSON export is stored for recovery or automation.

Next steps

Start typing to search every guide.