API Overview

All API endpoints are prefixed with /api. The server listens on port 3000 by default.

Base URL

http://localhost:3000/api

Content Types

Direction	Content-Type
Request (JSON)	application/json
Request (Binary)	application/octet-stream
Response (PDF)	application/pdf
Response (JSON)	application/json

Authentication

If enabled, all requests require HTTP Basic Auth. See the Authentication guide for details.

Unprotected endpoints: POST /api/login, GET /api/health

Rate Limiting

Limit Type	Window	Max Requests
General	60s	REPORTS_RATE_LIMIT (default 100)
Compilation	60s	1/4 of general limit

Rate limit headers are included in responses:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Standard Error Response

{
  "status": "error",
  "error": "Description of what went wrong"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	Deleted (no content)
400	Bad request / validation error
401	Unauthorized (auth required)
404	Not found
413	Payload too large
429	Rate limited
500	Internal server error

Endpoints Summary

Method	Path	Auth	Description
POST	/api/login	No	Authenticate with user/password
POST	/api/change-password	Yes	Change current password
POST	/api/preview	Yes	Compile inline Typst to PDF
POST	/api/report	Yes	Compile saved template to PDF
GET	/api/templates	Yes	List all templates
GET	/api/templates/:name	Yes	Get template content + metadata
PUT/POST	/api/templates/:name	Yes	Create or update template
DELETE	/api/templates/:name	Yes	Delete a template
GET	/api/folders	Yes	List template folders
POST	/api/folders	Yes	Create a template folder
DELETE	/api/folders/:name	Yes	Delete a template folder
GET	/api/assets	Yes	List all assets (?prefix=)
GET	/api/assets/:name	Yes	Get asset file
POST/PUT	/api/assets/:name	Yes	Upload asset
DELETE	/api/assets/:name	Yes	Delete asset
POST	/api/assets/folders	Yes	Create asset folder
DELETE	/api/assets/folders/:name	Yes	Delete asset folder
GET	/api/packages	Yes	List installed packages
POST	/api/packages	Yes	Install a package
DELETE	/api/packages/:name/:version	Yes	Delete a package
POST	/api/packages/check	Yes	Check content for missing packages
GET	/api/health	No	Health check
GET	/api/metrics	Yes	Server metrics