Connect and update API specifications

API Fleet uses OpenAPI documents as the source for endpoint, schema, and endpoint-list blocks. Connect the specification before building the portal so reference content stays linked to the API contract.

Choose a source

Use GitHub Sync when the specification belongs in a repository and changes through pull requests. Use Paste a spec for evaluation, a local file, or a contract that is not yet stored in GitHub.

GitLab sync is not available in the current product. Do not design a workflow that depends on it yet.

Paste YAML or JSON

1. Open Connected specs.
2. Choose Paste a spec.
3. Enter a stable filename such as payments.yaml.
4. Paste the complete OpenAPI document.
5. Save and confirm the title, version, operations, tags, and schemas.

Pasting another document is explicit; API Fleet will not monitor a local file. Use GitHub Sync when the spec should update automatically.

Connect GitHub

Install the GitHub App

1. Open GitHub Sync.
2. Choose Install GitHub App.
3. In GitHub, select the account and only the repositories API Fleet needs.
4. Return to API Fleet after installation.

Repository access is controlled by the GitHub App installation. Removing the installation or repository permission prevents future syncs but does not erase spec revisions already stored in the workspace.

Add a sync source

1. Select a repository.
2. Select the branch that represents documentation-ready changes.
3. Enter one or more file patterns, for example openapi/**/*.yaml.
4. Save the source.
5. Choose Sync now.

The background job reads the selected branch at a specific commit, finds files matching the pattern, parses valid OpenAPI documents, and stores new revisions for the active workspace.

Write useful file patterns

Prefer a narrow pattern so unrelated YAML files are not considered:

openapi/**/*.yaml
services/*/openapi.json

Keep filenames stable. Portal blocks reference the attached spec by spec_file; renaming a file may require attaching the new name and updating those blocks.

Understand latest and published versions

API Fleet intentionally separates two states:

• Latest is the most recent spec revision stored after paste or sync.
• Published is the revision pinned into the live portal build.

After a successful sync, the builder can show that the source has changed without altering client-facing documentation. Review the difference and publish the portal when the new contract and explanatory guides are ready.

Update a live portal safely

1. Sync the repository.
2. Open Connected specs and confirm the expected commit and files.
3. Open the portal and review affected spec-driven blocks.
4. Update guides, examples, and changelog content where necessary.
5. Preview the candidate portal.
6. Publish a new immutable build.

Do not auto-publish every repository commit. A valid OpenAPI change may still need migration guidance, examples, or coordinated release timing.

Improve the source document

For better generated reference content, include:

• Stable operationId values.
• Clear operation summaries and descriptions.
• Authentication schemes and requirements.
• Request and response examples.
• Error schemas and meaningful response descriptions.
• Tags that reflect client tasks.
• Server URLs appropriate for the audience.

Never place credentials or customer records in examples.

When a sync fails

Check the GitHub App installation, repository access, branch name, and pattern. Then validate the matching files as OpenAPI 3.x. See Troubleshooting for a focused checklist.