> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Reporter REST API
> Orient yourself in the Reporter API: the /v1 base path, bearer authentication, the 23 operations grouped by job, idempotency, pagination, and the RFC 9457 error shape.
Reporter serves one HTTP API. Every operation sits under the base path `/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](/en/reference/introduction). 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:
```http theme={null}
Authorization: Bearer
```
Reporter authorizes each request against the `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](/en/multi-tenancy).
## The operations by job
***
### Templates
Five operations own the template lifecycle: [list](/en/reference/reporter/list-templates), [upload](/en/reference/reporter/upload-template), [get](/en/reference/reporter/retrieve-template-details), [update](/en/reference/reporter/update-templates), and [delete](/en/reference/reporter/delete-template). 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](/en/reference/reporter/list-block-definitions) and [list filter definitions](/en/reference/reporter/list-filter-definitions) return the catalog an editor draws from. [Validate blocks](/en/reference/reporter/validate-template-blocks) checks a block tree and reports per-block errors. [Generate code](/en/reference/reporter/generate-template-code) turns that tree into template source you can then upload.
### Reports
Four operations, and only four: [create](/en/reference/reporter/create-report), [get](/en/reference/reporter/check-report-status), [list](/en/reference/reporter/retrieve-reports), and [download](/en/reference/reporter/download-report).
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](/en/reporter/reporter-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](/en/reference/reporter/list-data-sources) and [get one](/en/reference/reporter/retrieve-data-source), 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](/en/reference/reporter/retrieve-deadlines), [create](/en/reference/reporter/create-deadline), [update](/en/reference/reporter/update-deadline), [delete](/en/reference/reporter/delete-deadline), [deliver](/en/reference/reporter/deliver-deadline), and [notifications](/en/reference/reporter/retrieve-deadline-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](/en/reference/reporter/get-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](/en/reference/reporter/get-streaming-events) returns the event manifest covered in [Events](/en/reporter/reporter-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: true` on it.
## Pagination
***
List operations use offset pagination with the same two parameters.
| Parameter | Default | Rules |
| --------- | ------- | ----------------------------------------------------------------------------- |
| `page` | `1` | Page number. |
| `limit` | `10` | Items per page. The ceiling is `MAX_PAGINATION_LIMIT`, which defaults to 100. |
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](https://www.rfc-editor.org/rfc/rfc9457), carrying a `title`, a `status`, a `detail`, and a stable domain `code`. Match on the code, never on the prose. The [Reporter error list](/en/reference/reporter/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
***
The 23 operations, with full request and response shapes.
Upload a template, generate a report, and download it with cURL.
Subscribe to report and deadline events instead of polling.
Templates, reports, data sources, and where they fit.