> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Report presets

> Save editable org-scoped Gu1 report configurations for one-click download and scheduled send_report automations.

## Overview

A **report preset** stores a Gu1 [report template](/en/api-reference/entities/report-templates) configuration for your organization (`name` + `templateCode` + `params`). After create you can **edit** `name`, `description`, and `params`; `templateCode` stays fixed. You can also list, get, run, or delete.

| Method   | Path                       | Use                                           |
| -------- | -------------------------- | --------------------------------------------- |
| `GET`    | `/report-presets`          | List presets for the org                      |
| `GET`    | `/report-presets/{id}`     | Detail                                        |
| `POST`   | `/report-presets`          | Create (name + template + params)             |
| `PATCH`  | `/report-presets/{id}`     | Update name, description, and/or params       |
| `DELETE` | `/report-presets/{id}`     | Hard delete                                   |
| `POST`   | `/report-presets/{id}/run` | Run with saved params (`download` or `email`) |

Cap: **50** presets per organization. Unique name per org (case-insensitive).

**Run** always queues an async job to object storage (**202** + `jobId`). Download later from Reporting **Descargables** / [Report export jobs](/en/api-reference/entities/report-export-jobs). Saved `params` may include `emailLocale`, `format` (`csv` / `pdf` / `xlsx` per template), and other fields (`lookbackDays`, `ruleIds`, `filters`).

## Authentication and tenant

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY` — see [Authentication](/en/api-reference/authentication).
</ParamField>

<ParamField header="X-Organization-ID" type="string" required>
  Production or sandbox organization UUID — see [Environments](/en/api-reference/environments).
</ParamField>

## Permissions

| Endpoint                               | Granular permission |
| -------------------------------------- | ------------------- |
| `GET` list / get                       | `reports:read`      |
| `POST` create / run, `PATCH`, `DELETE` | `reports:export`    |

## Create

```
POST http://api.gu1.ai/report-presets
```

<ParamField body="name" type="string" required>
  Display name (1–120 characters). Must be unique within the organization (case-insensitive).
</ParamField>

<ParamField body="description" type="string">
  Optional note for your team (max 500 characters).
</ParamField>

<ParamField body="templateCode" type="string" required>
  Code from the Gu1 catalog (for example `alerts_by_rules`).
</ParamField>

<ParamField body="params" type="object">
  Template params (`lookbackDays`, `ruleIds`, `emailLocale`, `format`, `filters`, etc.). Validated against the template.
</ParamField>

On create, Gu1 stores a human-readable **`paramsSummary`** (rule names, lookback) for UI. At **run** time, live `params` UUIDs are used; missing rules are skipped by the runner.

### Example

```json theme={null}
{
  "name": "CBU/CVU account threshold",
  "description": "Monthly ops review",
  "templateCode": "alerts_by_rules",
  "params": {
    "lookbackDays": 30,
    "ruleIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
  }
}
```

### 201 response

```json theme={null}
{
  "success": true,
  "preset": {
    "id": "…",
    "organizationId": "…",
    "name": "CBU/CVU account threshold",
    "templateCode": "alerts_by_rules",
    "params": { "lookbackDays": 30, "ruleIds": ["…"] },
    "paramsSummary": {
      "lookbackDays": 30,
      "ruleLabels": ["Total accounts"],
      "lines": ["Last 30 days", "Rules: Total accounts"]
    },
    "createdAt": "2026-08-06T12:00:00.000Z"
  }
}
```

### Errors

| Code                        | Status | Meaning                 |
| --------------------------- | ------ | ----------------------- |
| `REPORT_TEMPLATE_NOT_FOUND` | 400    | Unknown `templateCode`  |
| `REPORT_PRESET_NAME_EXISTS` | 409    | Duplicate name in org   |
| `REPORT_PRESET_LIMIT`       | 400    | Cap of 50 reached       |
| `REPORT_PRESET_NOT_FOUND`   | 404    | Unknown id for this org |

## Update

```
PATCH http://api.gu1.ai/report-presets/{id}
```

At least one of `name`, `description`, or `params` is required. `templateCode` cannot change. `params` are re-validated against the existing template.

<ParamField body="name" type="string">
  New name (1–120). Must remain unique in the org.
</ParamField>

<ParamField body="description" type="string">
  New description (max 500) or `null` to clear.
</ParamField>

<ParamField body="params" type="object">
  Full params to persist (replacement, not a partial merge of omitted keys).
</ParamField>

## Run

```
POST http://api.gu1.ai/report-presets/{id}/run
```

Loads the preset and calls the same runner as `POST /report-templates/{code}/run` with saved `params`.

<ParamField body="delivery" type="string">
  `download` (default) or `email`.
</ParamField>

<ParamField body="recipientEmails" type="string[]">
  Required when `delivery` is `email`.
</ParamField>

<ParamField body="format" type="string">
  Optional: `csv`, `xlsx`, or `pdf` (must be supported by the template). If omitted, uses `params.format` or the template default.
</ParamField>

Successful response: **202** (same shape as report-templates run, plus `presetId`). Always queues a background job. Poll or download via [Report export jobs](/en/api-reference/entities/report-export-jobs).

## Automations

In Reporting, **Schedule** deep-links to the workflow builder with `reportPresetId` (canonical). Use automation action **`send_report` / Generar reporte** with `reportPresetId` and optional `sendEmail` + `recipientEmails`; legacy `reportTemplateCode` + `params` still works.