# Public API and Limits

The published documentation is served by a read-only **public API** that needs no sign-in. The [portal](/documentation/public-site-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.

```bash
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](/documentation/public-site-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](/documentation/configuration).

## Next steps

- [Deploy the Public Site](/documentation/public-site-portal)
- [Published Versions](/documentation/public-site-versions)
- [API Reference](/documentation/api-reference)

---
Source: https://selfdochub.com/documentation/public-site-api
