/v1, with no product segment ahead of it. A template list is GET /v1/templates.
The API carries 28 operations across seven areas: templates, the template builder, reports, data sources, deadlines, metrics, and the streaming manifest. All 28 render under the Reporter anchor in the API Reference. 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: 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
Seven operations manage the persisted registry under/v1/data-sources (note the hyphen). You can list or create entries, get, partially update, or soft-delete one by dataSourceId, inspect its live schema, and test its connection. Passwords are write-only, encrypted at rest, and absent from every response. A delete is refused while a live template still references the data source. Single-tenant deployments may seed registry entries from DATASOURCE_* variables at startup. Multi-tenant deployments create them per tenant through the API.
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
Template, deadline, and data-source lists 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 uses keyset pagination instead: send limit without page, then follow nextCursor or prevCursor from the response. A cursor is absent when there is no page in that direction, and the response does not include page or total. The report list accepts status, template_id, created_at, and sort_order. The cursor carries the sort order for the walk. 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 28 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.