Nibleaf API and OpenAPI reference

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:

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.

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.

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.