<!-- https://developers.silktide.com/v1/governance/reports/create-report | Governance / Reports -->

# Create a live report or a snapshot

`POST /v1/reports`

Creates a report from a [report template](https://developers.silktide.com/v1/governance/report-templates.md), and builds it. The response is the new report, as [Get a report](https://developers.silktide.com/v1/governance/reports/get-report.md) returns it, with status `200`.

`isLive` decides what you get, and defaults to `false`:

- **A snapshot** (`false`) is built now, over the dates `durationInterval` and `durationPeriod` count back from now, and never changes. Its `startTime` and `endTime` record those dates. The request takes as long as building it.
- **A live report** (`true`) is a dashboard: it is built afresh, over the same length of time back from then, every time you [read its results](https://developers.silktide.com/v1/governance/reports/get-report-results.md).

`reportTemplateId` is required; [List report templates](https://developers.silktide.com/v1/governance/report-templates/list-report-templates.md) has them. `context` must be in the shape the template's `contextTypeId` takes (see [Context](https://developers.silktide.com/v1/concepts/context.md)). Ids may be numbers or strings of digits; they are stored as numbers. Silktide does not check it when you create the report: a context that does not fit is saved, and the report then shows no results for it.

Its creator is the API key, an `a:` [assignee](https://developers.silktide.com/v1/platform/assignees.md) in `creatorAssigneeId`, and a live report is always built with its creator's permissions. Silktide names the report when you leave `name` out, such as "Broken links dashboard" or "Spelling report for Wine Barrel".

## Request

### Body

- `report` (object, required): The report.
  - `reportTemplateId` (string, required, 1 to 16 characters): The report template to build it from. Required.
  - `name` (string, optional): Its name. Left out or empty, Silktide names it from the template and what it covers.
  - `isLive` (boolean, optional): `true` for a live report (a dashboard), `false` for a snapshot. Defaults to `false`.
  - `durationInterval` (string, optional): The unit of how far back it looks. Defaults to `day`. One of: `day`, `week`, `month`, `year`.
  - `durationPeriod` (integer, optional, 1 to 90): How many `durationInterval`s back it looks, up to `90`. Defaults to `30`.
  - `context` (object or map of any JSON or empty list, optional): What it covers, in the shape the template's `contextTypeId` takes. Left out, it has none: a `websites` report then covers every website, and a `website` report shows no results.
    - `websiteId` (integer, required, at least 1): The website.
    - `sectionId` (integer, required): One of its sections. `0` for the whole website.

## Response

Status `200`.

- `report` (object, required): The new report.
  - `reportId` (integer, required, at least 1): The report.
  - `reportTemplateId` (string, required, 1 to 16 characters): The report template it is made from.
  - `reportScheduleId` (integer, required): The report schedule that made it. `0` when it was not made by a schedule.
  - `contextTypeId` (string, required): What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`. One of: `website`, `websites`, `account`, `property`.
  - `name` (string, required, at least 1 characters): Its name.
  - `thumbnailUrl` (string, required): A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created.
  - `startTime` (integer, required): For a snapshot, the start of the dates it covers. `0` for a live report.
  - `endTime` (integer, required): For a snapshot, the end of the dates it covers. `0` for a live report.
  - `durationInterval` (string, required): The unit of how far back it looks. One of: `day`, `week`, `month`, `year`.
  - `durationPeriod` (integer, required, 0 to 90): How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks.
  - `created` (integer, required): When it was created.
  - `creatorAssigneeId` (string, required): The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself.
  - `context` (object or map of any JSON or empty list, required): What it covers, in the shape its `contextTypeId` takes: `{"websiteId": 3, "sectionId": 0}` for one website, `{"criteria": {...}}` for several. `[]` when it has none.
    - `websiteId` (integer, required, at least 1): The website.
    - `sectionId` (integer, required): One of its sections. `0` for the whole website.
  - `isLive` (boolean, required): `true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created.
  - `version` (integer, required, at least 1): The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on.
- `permissions` (object, required): Who may see and admin the report.
  - `components` (list of objects, required): The permissions a report has: one to see it, one to admin it.
    - `permissionId` (string, required): The permission, such as `Report-ReportRead`.
    - `componentType` (string, required): What can be given it. `assignees` for users and roles.
    - `label` (string, required): Its name, such as `Can see this dashboard / snapshot`.
    - `description` (string, required, can be null): What it allows. Null for these permissions.
    - `inheritedPermissionIds` (list of strings, required): Permissions that include this one: anyone with those has this too.
    - `models` (list of any JSON, required): Reserved. Empty for these permissions.
  - `componentValues` (map of list of strings, required): Who was given each permission on this report directly, as assignee ids (`u:` users, `g:` roles).
  - `fixedValues` (map of list of strings, required): Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 403 | `EditionNotAvailable` | The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. |
| 403 | `AccessDenied` | The API key's user cannot create dashboards and snapshots. |
| 400 | `InvalidRequest` | `report` is not an object; `reportTemplateId` is missing or names no report template the API key's user can see; `name` contains `<`, `>` or control characters; `durationPeriod` is not a whole number from 1 to 90; `durationInterval` is not one of its values; or `isLive` is not true or false. `properties.field` names the field. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: Can create new dashboards and snapshots
- Plan feature: none
- Edition: Silktide 4 only
- Cost: free
- Stability: stable, since 1.0.0

## Example: A live broken links report on one website

```bash
curl -X POST "https://api.eu.silktide.com/v1/reports" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "reportTemplateId": "broken-links",
    "isLive": true,
    "durationInterval": "week",
    "durationPeriod": 4,
    "context": {
      "websiteId": 3,
      "sectionId": 0
    }
  }
}'
```

Response:

```json
{
  "report": {
    "reportId": 5,
    "reportTemplateId": "broken-links",
    "reportScheduleId": 0,
    "contextTypeId": "website",
    "name": "Broken links dashboard",
    "thumbnailUrl": "",
    "startTime": 0,
    "endTime": 0,
    "durationInterval": "week",
    "durationPeriod": 4,
    "created": 1794235546,
    "creatorAssigneeId": "a:3",
    "context": {
      "websiteId": 3,
      "sectionId": 0
    },
    "isLive": true,
    "version": 3
  },
  "permissions": {
    "components": [
      {
        "permissionId": "Report-ReportRead",
        "componentType": "assignees",
        "label": "Can see this dashboard / snapshot",
        "description": null,
        "inheritedPermissionIds": [
          "Report-ReportAdmin",
          "Report-ReportReadAll"
        ],
        "models": []
      },
      {
        "permissionId": "Report-ReportAdmin",
        "componentType": "assignees",
        "label": "Can admin this dashboard / snapshot",
        "description": null,
        "inheritedPermissionIds": [
          "Report-ReportAdminAll"
        ],
        "models": []
      }
    ],
    "componentValues": {
      "Report-ReportRead": [],
      "Report-ReportAdmin": []
    },
    "fixedValues": {
      "Report-ReportRead": [],
      "Report-ReportAdmin": [],
      "Report-ReportReadAll": [
        "g:2",
        "u:eu-12"
      ],
      "Report-ReportAdminAll": [
        "g:2",
        "u:eu-12"
      ]
    }
  }
}
```

## Example: A snapshot of the last 30 days, for websites tagged pre-production

```bash
curl -X POST "https://api.eu.silktide.com/v1/reports" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "reportTemplateId": "websites",
    "name": "Pre-production websites, last 30 days",
    "context": {
      "criteria": {
        "tagIds": [
          "pre-production"
        ]
      }
    }
  }
}'
```

Response:

```json
{
  "report": {
    "reportId": 6,
    "reportTemplateId": "websites",
    "reportScheduleId": 0,
    "contextTypeId": "websites",
    "name": "Pre-production websites, last 30 days",
    "thumbnailUrl": "",
    "startTime": 1791643553,
    "endTime": 1794235553,
    "durationInterval": "day",
    "durationPeriod": 30,
    "created": 1794235553,
    "creatorAssigneeId": "a:3",
    "context": {
      "criteria": {
        "tagIds": [
          "pre-production"
        ]
      }
    },
    "isLive": false,
    "version": 3
  },
  "permissions": {
    "components": [
      {
        "permissionId": "Report-ReportRead",
        "componentType": "assignees",
        "label": "Can see this dashboard / snapshot",
        "description": null,
        "inheritedPermissionIds": [
          "Report-ReportAdmin",
          "Report-ReportReadAll"
        ],
        "models": []
      },
      {
        "permissionId": "Report-ReportAdmin",
        "componentType": "assignees",
        "label": "Can admin this dashboard / snapshot",
        "description": null,
        "inheritedPermissionIds": [
          "Report-ReportAdminAll"
        ],
        "models": []
      }
    ],
    "componentValues": {
      "Report-ReportRead": [],
      "Report-ReportAdmin": []
    },
    "fixedValues": {
      "Report-ReportRead": [],
      "Report-ReportAdmin": [],
      "Report-ReportReadAll": [
        "g:2",
        "u:eu-12"
      ],
      "Report-ReportAdminAll": [
        "g:2",
        "u:eu-12"
      ]
    }
  }
}
```