> ## 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

<Tip>
  **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).
</Tip>

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 file content must match the desired output format (HTML, XML, CSV, TXT), but the file itself must have a `.tpl` extension.

<Tip>
  API reference: [Upload template](/en/reference/reporter/upload-template)
</Tip>

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -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"
}
```

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.

<Tip>
  API reference: [List templates](/en/reference/reporter/list-templates)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

## Step 3: Generate a report

***

Submit a report generation request with the template ID and optional filters to narrow the data.

<Tip>
  API reference: [Create report](/en/reference/reporter/create-report)
</Tip>

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/reports" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -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",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "created_at": {
          "between": ["2026-03-01", "2026-03-05"]
        }
      }
    }
  },
  "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"] }`             |

<Info>
  Filters are optional. Omit them to generate a report with all available data.
</Info>

## Step 4: Check report status

***

Report generation is asynchronous. Poll the status endpoint until the report is ready.

<Tip>
  API reference: [Check report status](/en/reference/reporter/check-report-status)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

| Status              | Meaning                                                                           |
| ------------------- | --------------------------------------------------------------------------------- |
| `Processing`        | Reporter is querying data and rendering the template                              |
| `PendingExtraction` | The report is waiting for data extraction to complete before generation can begin |
| `Finished`          | The report is ready for download                                                  |
| `Error`             | An error occurred during generation                                               |

Wait for `Finished` before proceeding to download.

## Step 5: Download the report

***

Once the report is finished, download the generated file.

<Tip>
  API reference: [Download report](/en/reference/reporter/download-report)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -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 and their schemas.

<Tip>
  API reference: [List data sources](/en/reference/reporter/list-data-sources) | [Retrieve data source](/en/reference/reporter/retrieve-data-source)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/data-sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

Each data source includes available tables and fields that you can reference in your templates using the `{{ datasource.table.field }}` syntax.

## Next steps

***

<CardGroup cols={2}>
  <Card title="What is Reporter?" icon="circle-info" href="/en/reporter/what-is-reporter">
    Full overview of template syntax, tags, and filters.
  </Card>

  <Card title="Template formats" icon="file-code" href="/en/reporter/template-examples">
    Practical examples for HTML, XML, and TXT templates.
  </Card>

  <Card title="Using Reporter" icon="rocket" href="/en/reporter/using-reporter">
    Detailed guide on templates, storage, and data source configuration.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/en/reference/reporter/reporter-error-list">
    Complete list of error codes and how to resolve them.
  </Card>
</CardGroup>