API Reference

Velkin exposes a small, focused REST API. Most endpoints accept and return JSON; the render-* endpoints stream the rendered file as the response body.

This reference is organised by resource:

• Reports — create, read, update, and delete reports, manage their template assets, and the report body schema.
• Rendering — render to PDF/DOCX/XLSX and the Studio preview endpoints.
• History — per-file version history and named commits.
• Errors — the shared error envelope and every error code.

Base URL

http://<your-host>:8081/api

With the default Docker Compose setup the API is published on host port 8081. The Angular Studio is served separately on :8080 and proxies /api/* to the backend, so a browser on the Studio origin can also use a relative /api/... path (i.e. http://<your-host>:8080/api).

No authentication

Velkin ships no built-in authentication or API keys. There is no /auth/login, no bearer token, no login screen. Every endpoint is reachable by anyone who can reach the port. This is deliberate for trusted internal deployments — secure the service at the network layer. Read the Security model before exposing it.

Request rules (CSRF & content type)

Mutating requests (POST, PUT, PATCH, DELETE) are subject to two checks:

• Sec-Fetch-Site must not be cross-site. Browsers set this header automatically; a request from another origin is rejected with 403 csrf_blocked. Non-browser clients (curl, your backend) don't send the header and pass.
• Content-Type of a request with a body must be application/json or multipart/form-data, otherwise 415 unsupported_media_type.

OPTIONS requests short-circuit to 204 No Content with an Allow header.

Health

Method	Path	Response
GET	/healthz	204 No Content if up.

Note /healthz is not under /api.