Public API and Limits
The published documentation is served by a read-only public API that needs no sign-in. The portal uses it, and you can call it from your own site too. This page lists the resources and the settings that control access.
Roles: The API is public. Its settings are server configuration, set by whoever runs the installation. It exists only while the license includes
publish.
The domain header#
Every request names the site it is about in the X-Public-Domain header, for example docs.example.com. SelfDocHub answers with the data of that domain. An unknown domain, a hidden or still building version and a missing file all answer the same 404, so the API does not reveal what exists.
curl -H "X-Public-Domain: docs.example.com" https://hub.example.com/public/v1/site
Resources#
| Method and path | Returns |
|---|---|
GET /public/v1/site |
Site texts and languages, the final design tokens of the light and dark scheme, branding, top bar, footer, the versions in order and the default version. |
GET /public/v1/branding/{kind} |
A logo or the favicon. |
GET /public/v1/i18n/{lang} |
Interface texts of the site in a language. |
GET /public/v1/versions/{id}/tree |
The menu of a version: services and their tree. |
GET /public/v1/versions/{id}/endpoints/{node} |
An endpoint, in one simplified form for OpenAPI, GraphQL, AsyncAPI and OpenRPC. |
GET /public/v1/versions/{id}/pages/{node} |
A text page. |
GET /public/v1/versions/{id}/assets/{name} |
A picture of a page. |
GET /public/v1/versions/{id}/search?q= |
Simple search over titles, paths and first lines. |
GET /public/v1/versions/{id}/sitemap |
The addresses of a version, for a sitemap. |
GET /public/v1/openapi.json |
The OpenAPI document of this API. |
The OpenAPI document of the public API is a separate document from the one of the admin API.
Hidden versions and preview tokens#
A hidden version is served when the request carries a valid X-Preview-Token header. The token comes from the Preview on the site action of a version and works for one hour. See Published Versions.
Caching#
Responses carry an ETag, and a repeated request with If-None-Match answers 304. They also carry Cache-Control. Requests with a preview token are never cached by shared caches.
Settings#
| Setting | Environment variable | Default | Purpose |
|---|---|---|---|
public_cors_origins |
DOCS_HUB_PUBLIC_CORS_ORIGINS |
* |
Origins that browsers may call the public API from. * allows any, a comma-separated list allows some, empty allows none. The portal calls the API from its server, so it does not need CORS. |
public_rate_per_ip |
DOCS_HUB_PUBLIC_RATE_PER_IP |
1200 |
Requests per minute from one address. 0 turns the limit off. The address is the TCP peer; X-Forwarded-For is not trusted. |
public_rate_per_domain |
DOCS_HUB_PUBLIC_RATE_PER_DOMAIN |
6000 |
Requests per minute for one published domain. 0 turns the limit off. |
A request over a limit answers 429. The portal calls the hub from its own server and does not pass the reader's address on, so all readers of the portal count as one address. With the default of 1200 requests per minute per address this can become a bottleneck on a busy site: raise public_rate_per_ip or turn it off (0) when the hub is reachable from the portal only, and keep public_rate_per_domain as the protection. See Configuration Reference.