> ## 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 API quick start
> Get Reporter running in minutes: upload your first template, generate a report, and download the finished output with cURL against the Reporter API.
**This guide is intended for developers.** If you're looking for a business-level overview of what Reporter does, see [What is Reporter?](/en/reporter/what-is-reporter).
Get Reporter running in minutes. This guide walks you through the complete journey, from uploading your first template to downloading a generated report.
## Before you begin
***
You need:
* A running Reporter instance
* A valid authentication token (if Access Manager is enabled)
* A `.tpl` template file ready to upload
All examples use `cURL`. Replace `$TOKEN` with your authentication token and `https://reporter.example.com` with your Reporter URL.
## Step 1: Upload a template
***
Upload a `.tpl` file that defines the structure and content of your report. The template content must match the selected output format: HTML for `HTML` and `PDF`, XML for `XML`, CSV for `CSV`, and non-empty text for `TXT`. The uploaded file itself must have a `.tpl` extension.
API reference: [Upload template](/en/reference/reporter/upload-template)
```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/templates" \
-H "Authorization: Bearer $TOKEN" \
-F "template=@account_summary.tpl" \
-F "outputFormat=PDF" \
-F "description=Daily account summary report"
```
```json theme={null}
{
"id": "0196b270-a315-7137-9408-3f16af2685e1",
"outputFormat": "pdf",
"description": "Daily account summary report",
"fileName": "0196b270-a315-7137-9408-3f16af2685e1.tpl",
"createdAt": "2026-03-05T10:00:00Z",
"updatedAt": "2026-03-05T10:00:00Z"
}
```
Save the template `id`. You will use it to generate reports.
### Supported output formats
| Format | Use case |
| ------ | ------------------------------------------ |
| `CSV` | Data exports and spreadsheet integration |
| `XML` | Structured data and regulatory submissions |
| `HTML` | Browser-viewable reports |
| `PDF` | Print-ready and shareable documents |
| `TXT` | Plain text and legacy system integration |
## Step 2: Verify the template
***
List your templates to confirm the upload was successful.
API reference: [List templates](/en/reference/reporter/list-templates)
```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/templates" \
-H "Authorization: Bearer $TOKEN"
```
## Step 3: Generate a report
***
Submit a report generation request with the template ID and the required `filters` object. Add filters to narrow the data, or send `{}` when no filtering is needed.
API reference: [Create report](/en/reference/reporter/create-report)
```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/reports" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"templateId": "0196b270-a315-7137-9408-3f16af2685e1",
"filters": {
"midaz_onboarding": {
"account": {
"created_at": {
"between": ["2026-03-01", "2026-03-05"]
}
}
}
}
}'
```
```json theme={null}
{
"id": "0196c5c0-5044-724f-95f3-4b32076e7ad7",
"templateId": "0196b270-a315-7137-9408-3f16af2685e1",
"templateOutputFormat": "pdf",
"templateDescription": "Daily account summary report",
"filters": {
"midaz_onboarding": {
"account": {
"created_at": {
"between": ["2026-03-01", "2026-03-05"]
}
}
}
},
"status": "Processing",
"metadata": null,
"completedAt": null,
"createdAt": "2026-03-05T10:05:00Z",
"updatedAt": "2026-03-05T10:05:00Z",
"deletedAt": null
}
```
Save the report `id` for the next steps.
### Filter structure
Filters follow the path: **data source > table > field > operator > values**.
| Operator | Description | Example |
| ------------ | ------------------------------- | --------------------------------------------- |
| `eq` | Equal to | `{ "eq": ["active"] }` |
| `gt` / `gte` | Greater than / greater or equal | `{ "gte": ["2026-01-01"] }` |
| `lt` / `lte` | Less than / less or equal | `{ "lt": [1000] }` |
| `between` | Value within a range | `{ "between": ["2026-03-01", "2026-03-31"] }` |
| `in` / `nin` | Value in / not in a list | `{ "in": ["active", "pending"] }` |
The `filters` field is required. To generate a report without filtering, pass an empty object: `"filters": {}`.
## Step 4: Check report status
***
Report generation is asynchronous. Poll the status endpoint until the report is ready.
API reference: [Check report status](/en/reference/reporter/check-report-status)
```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
-H "Authorization: Bearer $TOKEN"
```
| Status | Meaning |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `Processing` | Reporter is querying data and rendering the template |
| `Finished` | The report is ready for download |
| `Partial` | Some data sections succeeded and others failed; the report's `metadata` carries per-section error codes |
| `Error` | An error prevented the report from being generated. |
Wait for `Finished` before proceeding to download.
## Step 5: Download the report
***
Once the report is finished, download the generated file.
API reference: [Download report](/en/reference/reporter/download-report)
```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
-H "Authorization: Bearer $TOKEN" \
-o account_summary.pdf
```
The file is returned with `Content-Disposition` headers indicating the filename and format.
## Step 6: Explore data sources
***
To understand what data is available for your templates, list the configured data sources. Then use `GET /v1/data-sources/{dataSourceId}` to inspect the schema of one data source.
API reference: [List data sources](/en/reference/reporter/list-data-sources) | [Retrieve data source](/en/reference/reporter/retrieve-data-source)
```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/data-sources" \
-H "Authorization: Bearer $TOKEN"
```
The list response identifies each data source. The detail response includes its available tables and fields, which you can reference in your templates using the `{{ datasource.table.field }}` syntax.
## Next steps
***
Full overview of template syntax, tags, and filters.
Practical examples for HTML, XML, and TXT templates.
Detailed guide on templates, storage, and data source configuration.
Complete list of error codes and how to resolve them.