Content
Portal API reference
Publish one interactive API reference on your API Portal from a full OpenAPI spec. Add custom endpoint descriptions and validate the spec against a Spectral ruleset. This is your own API, not the Apiable Platform API.
The portal API reference is one interactive API reference you publish on your API Portal from a full OpenAPI spec. You manage it under Content, API Reference. Apiable renders your spec as a browsable reference, and you can add custom endpoint descriptions and a Spectral ruleset.
How do you publish a portal API reference?
Open Content, API Reference, upload your full OpenAPI spec, then turn on the Published toggle. The Public toggle controls whether unauthenticated visitors can see it. Uploading a spec needs a role that can manage portals.
- Open Content, API Reference.
- Upload your full OpenAPI spec. The file is checked as an API spec on upload.
- Choose Upload to save the spec. The reference renders in the preview.
- Turn on Published, and set Public for visibility.
What is on the API Reference page?
The page has a title, two toggles, an upload control, a download button, an instructions panel, and a live render of the spec. Until you upload a spec, the render area shows an empty state.
| Element | What it does |
|---|---|
| Title | The reference title, editable at the top. Defaults to API Reference. |
| Public | Whether unauthenticated visitors can see the reference. |
| Published | Whether the reference is live on the portal. |
| Upload control | Uploads a full OpenAPI spec. The file is validated as an API spec. |
| Download button | Downloads the current spec file. |
| Instructions | A panel of guidance shown beside the upload control. |
| Reference render | Renders the uploaded spec. Shows No API Reference uploaded until you add one. |
How is this different from the Apiable Platform API reference?
The portal API reference renders your own API spec for your developers. The Apiable Platform API reference documents Apiable's own API for managing your account. They serve different audiences and live in different places.
| Portal API reference | Apiable Platform API reference | |
|---|---|---|
| Whose API | Your API | Apiable's API |
| Audience | Your developers, on your portal | You, integrating with Apiable |
| Where you set it | Content, API Reference in the dashboard | Not configured; it is Apiable's published reference |
| Where it lives | Your API Portal | /docs/api-reference/ |
How do you add custom endpoint descriptions?
The reference supports a custom description for each endpoint. You set a description per endpoint, keyed by its operation, method, and path. The reference saves it alongside the spec, so your wording shows in place of, or in addition to, the spec's own text.
This lets you explain an endpoint in your own words without editing the source OpenAPI file. The descriptions are stored with the reference configuration, not in the uploaded spec.
How do you validate the spec?
The portal API reference carries an optional Spectral ruleset URL and a validation type. Spectral is the only validation type. Point it at your ruleset to check the spec against your rules.
What does the Cascade option do?
Cascade is a toggle on the API Reference page that controls cascade behavior for the reference. Turn it on or off, and the change saves immediately.
The toggle has its own label and description on the page. Use them to confirm the behavior before you change it.
Troubleshooting
| What you see | What to do |
|---|---|
| The reference shows No API Reference uploaded | No spec is uploaded yet. Upload your full OpenAPI spec, then choose Upload. |
| The Upload button is disabled | Either you have not changed the file, or your account lacks the role to manage portals. |
| The upload is rejected | The file did not validate as an API spec. Confirm it is a valid OpenAPI document. |
| The Public and Published toggles do nothing | Your account lacks the role to manage content items. |
| The reference does not appear on the portal | Confirm Published is on, then check Public if unauthenticated visitors cannot see it. |
Where to next
Content overview
See everything you can publish on your portal beyond product docs.
API spec viewer and validation
Tune the spec viewer and set the Spectral ruleset under portal settings.
Documentation hubs
Pair your API reference with written documentation pages.
Apiable Platform API
The reference for Apiable's own API, separate from your portal reference.