Skip to main content

API Reference

Invoicerr's backend exposes a fully documented REST API via Swagger/OpenAPI, generated from @nestjs/swagger decorators on every controller in backend/src/modules/.

Published Specification​

The OpenAPI document for the latest build on main is published alongside this site, so you can browse or import it without running your own instance or enabling Swagger in production (see Your Own Instance below):

  • Raw OpenAPI spec (JSON): docs.invoicerr.app/openapi.json — import this into Postman, Insomnia, a code generator, or any other OpenAPI-aware tool.

    (Linked as an absolute URL rather than a relative one deliberately: the file is a build-time artifact copied into static/ by CI, never committed to this repository — see that step's own comment in .github/workflows/docs-deploy.yml — so it does not exist for Docusaurus's broken-link checker to verify in a local checkout or a PR preview build that hasn't run that step.)

It is generated by npm run openapi:dump (backend/src/openapi-dump.ts) — the exact same DocumentBuilder configuration and controller metadata /api/docs-json serves on a running instance (backend/src/swagger-document.ts, shared by both) — and copied into this site's static/ directory as part of the documentation build (.github/workflows/docs-deploy.yml). This is also the interoperability reference the Terms of Service, Section 10, points to for the EU Data Act's Article 26/30 disclosure.

Your Own Instance​

Rather than duplicating the reference here, use the live, always-up-to-date Swagger UI served by your own Invoicerr instance:

  • Interactive UI: https://<your-instance>/api/docs
  • Raw OpenAPI spec (JSON): https://<your-instance>/api/docs-json

For a local development setup (see Local Development), this is typically:

  • http://localhost:3000/api/docs
  • http://localhost:3000/api/docs-json

Swagger is served by default outside production. In production it is disabled unless SWAGGER_BASIC_AUTH_USER and SWAGGER_BASIC_AUTH_PASSWORD are both set (backend/src/main.ts), in which case it is mounted behind HTTP Basic Auth for every /api/docs* path. The published spec above covers exactly this gap for a hosted or otherwise Swagger-disabled instance.

Authentication​

Most endpoints require either a session cookie (browser login) or an API key. See Authentication for details on both mechanisms, and the api-keys module for managing keys from the UI.