/v1, with no product segment ahead of it. A template list is GET /v1/templates.
The API carries 23 operations across seven areas: templates, the template builder, reports, data sources, deadlines, metrics, and the streaming manifest. All 23 render under the Reporter anchor in the API Reference. This page is the map, not the territory. It covers what the operations share and points you at the reference page for each one.
The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for SDK generation.
Authentication
Reporter accepts a JWT bearer token. One security scheme applies to every operation:
reporter application, a resource, and an action. The resource follows the area — templates, reports, deadlines, data-source, metrics, or streaming. The action is the lower-cased HTTP method, so POST /v1/reports authorizes as the post action on reports. PLUGIN_AUTH_ENABLED turns the middleware on, and PLUGIN_AUTH_ADDRESS points it at the Access Manager.
Probe routes stay outside authentication so an orchestrator reaches them without a token: /health, /readyz, and /version.
Tenant identity travels inside the token. Reporter resolves the tenant from the JWT tenantId claim. None of the operations above take a tenant from a request header, and no client-supplied value overrides it. See Multi-tenancy.
The operations by job
Templates
Five operations own the template lifecycle: list, upload, get, update, and delete. A template is a plain-text.tpl file plus its output format and description. Deleting one also removes the deadlines that point at it.
Template builder
Four operations back a visual editor without persisting anything. List block definitions and list filter definitions return the catalog an editor draws from. Validate blocks checks a block tree and reports per-block errors. Generate code turns that tree into template source you can then upload.Reports
Four operations, and only four: create, get, list, and download. The lifecycle is create-and-retain.POST /v1/reports answers 201 with a report in Processing and hands the work to a background worker. The report then reaches Finished, Partial, or Error. Poll the get operation, or subscribe to the events described in Events. Download serves a report in Finished. Every report you create stays addressable by its identifier for as long as your object-storage retention policy keeps the artifact.
Data sources
Two read operations: list and get one, both under/v1/data-sources — note the hyphen. An operator registers data sources through environment variables, so these operations report what the deployment already has and expose no write path.
Deadlines
Six operations model a filing obligation with a due date and a recurrence rule: list, create, update, delete, deliver, and notifications. Status is derived from the due date and the delivery mark, never sent by a client. Notifications are pull-only: the operation returns the deadlines inside their alert window, sorted overdue first.Metrics and streaming
Metrics returns deployment counters — templates, reports, data sources, and report errors for the current window against the one before it.errorPeriodDays sets that window and defaults to 7. Streaming events returns the event manifest covered in Events.
Content types
Template create and update are
multipart/form-data: a template file part, plus outputFormat and description. Everything else that carries a body is application/json.
Download answers with the bytes and a Content-Disposition filename. The media type follows the report’s output format — application/pdf, application/xml, text/csv, text/html, or text/plain.
Idempotency
Template create and report create accept an
X-Idempotency request header. Send your own key, or omit the header and Reporter derives one from a hash of the request body.
- A request that repeats one still in flight is rejected rather than duplicated.
- A request that repeats one already completed replays the original response and stamps
X-Idempotency-Replayed: trueon it.
Pagination
List operations use offset pagination with the same two parameters.
A
limit above the ceiling is rejected with a pagination error rather than clamped. The report list also accepts a cursor parameter, which carries the position of the previous page in place of a page number.
The report list adds filters on top: status, template_id, output_format, description, type, active, a start_date/end_date window, and sort_order, which defaults to desc. The template list filters on outputFormat, and the deadline list on status.
Errors
Every error answers
application/problem+json and follows RFC 9457, carrying a title, a status, a detail, and a stable domain code. Match on the code, never on the prose. The Reporter error list maps each code to its HTTP status and its fix.
Reading the spec from a running service
SWAGGER_ENABLED=true mounts a browsable reference at /swagger/docs, with the OpenAPI 3.1 document at /swagger/openapi.json and /swagger/openapi.yaml. It is off unless you turn it on. Keep it off in production.
Next steps
API Reference
The 23 operations, with full request and response shapes.
API quick start
Upload a template, generate a report, and download it with cURL.
Events
Subscribe to report and deadline events instead of polling.
What is Reporter?
Templates, reports, data sources, and where they fit.