# Nibleaf API and OpenAPI reference

> Find the self-hosted server specification, understand browser-session authentication, and separate Nibleaf APIs from published customer API references.

The Nibleaf server exposes an OpenAPI-backed interactive reference at `/docs`
on API port 4311. In the development stack, open
`http://localhost:4311/docs`. In production, the API normally remains internal
and the app proxies browser requests under `/api` so session cookies stay first
party.

## Use the specification from the matching release

The running server specification is authoritative for its route paths, methods,
schemas, and response codes. Do not build an integration from a screenshot or a
specification generated by a different image tag.

For local development:

```bash
docker compose -f docker-compose.dev.yml up -d
pnpm db:generate
pnpm db:deploy
pnpm db:seed
pnpm dev
```

Open the API reference only after the server is running. The demo seed is for
local development and must not be enabled in production.

## Authentication boundary

Dashboard routes use the authenticated browser session and organization/project
authorization. The app's same-origin `/api` proxy is part of that design. Do not
publish port 4311 to the internet merely to make an internal integration easier.

Public site routes expose only reader-facing published content, search, metadata,
and explicitly public workflows. They do not grant dashboard privileges.
Operator and worker credentials are separate from reader and workspace access.

The authenticated HTTP MCP endpoint is a separate, explicit integration
contract. It is disabled by default, accepts project-bound API keys with
`mcp:connect` and exact read scopes, and does not turn undocumented dashboard
routes into a supported public write API. Its read adapters cover bounded
content, search, usage, entitlement, add-on, theme, integration, and operational
summaries. Theme-import preview validates without writing; publishing, reindex,
usage export, provider credentials, and new-domain mutations remain unavailable.
See [Connect MCP clients securely](/self-hosting/mcp).

## Integrate safely

- Use the OpenAPI document served by the target environment.
- Test with a least-privilege non-production workspace.
- Treat session cookies, bearer values, invitation tokens, and internal secrets
  as credentials; never embed them in documentation examples.
- Handle documented error responses and rate limits rather than retrying every
  failure indefinitely.
- Revalidate the specification and affected workflows before an upgrade.
- For MCP, rotate project-bound keys rather than reusing a browser session or a
  legacy wildcard key.

Nibleaf is pre-1.0, so undocumented internal routes are not a compatibility
contract. Propose stable integration needs through a public issue without
including private environment details.

## Published customer API references

The Nibleaf platform API and a documentation project's own API reference are
different products. To publish a project reference, open **Settings → API
Reference**, choose its navigation label and path, then use one supported source:

- upload or paste one JSON or YAML document up to 5 MB;
- fetch a public HTTP(S) URL without embedded credentials; or
- read a repository-relative file from a connected public GitHub or GitLab
  repository.

Nibleaf validates OpenAPI 3.x before saving. It resolves and bundles public
external `$ref` files into the stored document. Relative references work for URL
and repository sources; uploaded or pasted documents can reference absolute public
HTTP(S) URLs. The combined document is limited to 5 MB and 20 external files.
Every fetch is time- and size-bounded and rejects private-network destinations,
credentials, unsafe redirects, and DNS rebinding.

Publish after saving or refreshing the specification. The validated document
is frozen into that immutable deployment, so an older deployment or rollback
retains its own specification revision.

The published reference uses Scalar. Try-it requests go directly from the
reader's browser to the described API; Nibleaf does not proxy requests, inject
credentials, persist authentication, or log request secrets. The API must allow
the published documentation origin in its CORS policy. Test one harmless request
with temporary credentials and clear them before sharing a browser or recording
evidence.