The URL points at a private or internal address, or redirects to one. Use an address anyone on the internet can reach.
Publish an API reference
Turn your OpenAPI or GraphQL spec into API reference pages in your help center, with a playground where readers can send real requests. Readers find the operations in the same search as your articles, and your AI agent can answer from them.
Needs an active subscription or trial.
Add your spec
In Help Center, open a section's add menu and choose Create API reference. We read OpenAPI (JSON or YAML), Swagger 2.0, GraphQL SDL and GraphQL introspection JSON, up to 15 MB. Where the spec comes from decides how it stays current:
Source | How it stays current |
|---|---|
From GitHub | Updates when a push changes the spec file on the branch you chose. Needs GitHub connected. |
From a URL | We fetch it again every six hours. A GraphQL endpoint needs introspection turned on. |
Upload a file | Never on its own. Upload a new file with Replace spec. |
Use Refresh now to fetch a URL or GitHub source straight away, and Replace spec to switch to a different source. To document several API versions, add one reference per version.
Shape the pages
Everything else is in the reference's settings, so you don't need to edit the spec:
Choose how it sits in the sidebar (flat, as folders, or as one collapsed entry), reorder groups and give them icons.
Hide operations, schemas or GraphQL types readers don't need.
Change an operation's summary, add notes, or add Custom code samples. These overrides stay when the spec refreshes, as long as the operation keeps its method and path.
Code samples also come from the spec itself: x-codeSamples, and the SDK snippets in specs generated by Stainless.
The playground
Readers can click Try it on any operation, or use the playground page on a GraphQL reference, and send a real request. Requests go through our servers rather than the reader's browser, so your API needs no CORS setup. They can only reach the servers listed in your spec, or the GraphQL endpoint you set, and never private or internal addresses. Keys and headers readers type are sent with their request and never published with the reference.
Publish and limit access
Publish the reference to show it in your help center, or turn on Publish immediately when you create it. Unpublish API reference takes it offline and keeps your settings. Deleting it removes its pages for good.
A reference follows the access of its section. To show it only to some customers, put it in a section limited to their group. See Show content to specific readers.
Source errors
Blocked API specification URL host
Unable to resolve API specification URL host
The domain name doesn't exist. Check the URL for typos.
Only HTTP(S) API specification URLs are allowed, or the URL must not include embedded credentials
Use a plain http:// or https:// address with no username or password in it.
Could not fetch the spec from your host, or too many redirects
Your server returned an error or redirected more than five times. Check that the URL still serves the spec directly.
The URL returned neither a specification document nor a GraphQL schema
Point it at an OpenAPI file, a GraphQL SDL file, or a GraphQL endpoint with introspection turned on.
API specification exceeds the 15 MB limit
Make the spec smaller, for example by splitting it into one reference per API.
Could not authenticate with GitHub, or the GitHub connection cannot read that repository
Reconnect GitHub, or give your GitHub connection access to that repository, then click Refresh now.
The GitHub path must point at a file, or File not found in the GitHub repository
Check that the path is the spec file itself, not a folder, and that it exists on the branch or commit you chose.
Processing failed
We couldn't read the spec. Fix it and use Replace spec to try again.