/v1, with no product segment ahead of it. A template list is GET /v1/templates.
The API carries 56 operations across nine areas: templates, the template builder, reports, data sources, deadlines, institutions, regulatory filing, metrics, and the streaming manifest. All 56 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, institutions, regulatory, metrics, or streaming. Approving a regulatory draft authorizes against its own resource, regulatory-approval. 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
Nine operations own the template lifecycle: list, upload, get, get content, update, delete, and preview, plus list report families and assign a report family. A template is a plain-text.tpl file plus its output format, description, and category. Deleting a template 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, and a regulatory filing reaches Draft instead of Finished. Poll the get operation, or subscribe to the events described in Events. Download serves a report in Finished or Final, and a Draft only when no required field is blank. The X-Report-Status response header names the status you received. 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.
Institutions
Six operations register the financial institutions a tenant reports for: list, create, get, replace, delete, and propose from Midaz. An institution has one CNPJ and a scope that names its rows in each data source. A report request names the institution it reads for. When the tenant has several institutions, a request that names none is refused. Replace requiresIf-Match with the version you read.
Regulatory filing
Eighteen operations run the filing cycle for the curated regulatory documents that a deployment carries:- Catalog: list documents, get a document, and get its contract, which lists every field the file needs.
- Subscriptions: list, create, get, deactivate, reactivate, adopt another document version, and set the filing institution.
- Mapping: get and replace the YAML mapping from the document’s fields to your tables, and check it against the live databases.
- Filings: generate a draft, correct it, read the corrections, approve it, and read its provenance.
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, description, and category. The regulatory mapping is application/yaml. 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, data-source, and institution 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 output_format, category, has_category, description, data_source_name, and created_at. The deadline list filters on status, active, type, start_date, and end_date.
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 56 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.