# API Endpoints

Shaper provides API endpoints to create temporary dashboards, download data, generate reports and create images.

Use the API to integrate Shaper into your workflows and benefits from Shaper's approach of defining everything as SQL.


## Authentication

To authenticate API requests you need to generate an API key in the Shaper UI's Admin section.

Send the key as **Bearer token** in the `Authentication` header of the HTTP request.

The API key must have the required permissions for the endpoint you want to access. The required permissions are listed below of each endpoint.


## Supported file formats

The following file formats are supported for the download endpoints. The requested format is detected from the file extension in the request URL. For example, if the URL ends with `dashboard.csv`, the response is a CSV file. If the URL ends with `dashboard.xlsx`, the response is an Excel file.

| Format | Extension | Notes |
|--------|-----------|-------------|
| PDF    | `.pdf`    | Downloads the whole dashboard as PDF. Note that PDFs have a width that only allows for 2 cards next to each other. Plan the layout accordingly. The resulting PDF is A4 sized. Use [`HEADER_IMAGE`](/shaper/docs/dashboard-sql-reference#header_image) and [`FOOTER_LINK`](/shaper/docs/dashboard-sql-reference#footer_link) to adjust the PDF header and footer. |
| PNG  | `.png`    | Dashboard must contain exactly one chart. The chart is then downloaded. Tables and text cannot be downloaded as image file. |
| CSV    | `.csv`    | Dashboard must contain a `DOWNLOAD_CSV` button or dashboard only contains a single table/chart |
| Excel  | `.xlsx`   | Dashboard must contain a `DOWNLOAD_XLSX` button or dashboard only contains a single table/chart |
| JSON   | `.json`   | Dashboard must contain a `DOWNLOAD_JSON` button or dashboard only contains a single table/chart |

## Endpoints

### `POST /api/dashboards`

Create a temporary dashboard by sending SQL code in the request body.

Via API key authentication only temporary dashboards can be created. Dashboards are available for [tmp-dashboards-ttl](https://docs.taleshape.com/configuration#tmp-dashboards-ttl) (default: 24h).
For creating permanent dashboards we recommend the [file-based workflow](/shaper/docs/file-based-workflow) so that you can review and version control dashboards.

Internal users that have a login to Shaper can visit the dashboard at `/dashboards/:id`, and you can [embed](/shaper/docs/dashboard-embedding) temporary dashboards to show them to users directly in your own application.

**Required API Key Permission:** `data:query`

**Request:**

Send a JSON request body with the fields `temporary` set to `true` and `content` that contains the SQL that defines a dashboard.

```json
{
  "temporary": true,
  "content": "SELECT name, address FROM customers"
}
```

**Response:**

The response contains the `id` of the created dashboard.

```json
{
  "id": "123"
}
```

**Example:**

```bash
curl -X POST -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"temporary": true, "content": "SELECT name, address FROM customers"}' \
  "https://app.taleshape.com/api/dashboards"
```


### `GET /api/dashboards/:id/download/:file`

Download an existing dashboard as PDF, PNG, CSV, Excel or JSON file.

Add `?mode=url` to the URL to get a secure download URL instead of directly downloading the file. The URL is valid for [downloads-ttl](/shaper/docs/configuration-options#downloads-ttl) (default: `10 minutes`).

**Required API Key Permission:** `dashboard:read`

| Parameter | Description |
|-----------|-------------|
| `id`      | id of the dashboard to download |
| `file`    | filename + extensions to download. |

**Request:**

Send the `GET` request without request body.

**Response:**

The response is the file to download. The content type is set according to the file format.

If `?mode=url` is added to the request URL, the response is a JSON object with a `url` field that contains the secure download URL.

```json
{
  "url": "https://example.com/api/downloads/token/filename.pdf"
}
```

**Example:**

```bash
curl -H "Authorization: Bearer <API_KEY>" \
  "https://app.taleshape.com/api/dashboards/123/download/dashboard.pdf"
```

### `POST /api/download/:file`

Dynamically generate a file by sending SQL code in the request body.

Add `?mode=url` to the URL to get a secure download URL instead of directly downloading the file. The URL is valid for [downloads-ttl](/shaper/docs/configuration-options#downloads-ttl) (default: `10 minutes`).

**Required API Key Permission:** `data:query`

| Parameter | Description |
|-----------|-------------|
| `file`    | filename + extensions to download. |

**Request:**

Send a JSON request body with a `sql` field that contains the SQL that defines a dashboard, chart or a single query to download.

```json
{ sql: "" }
```

**Response:**

The response is the file to download. The content type is set according to the file format.

If `?mode=url` is added to the request URL, the response is a JSON object with a `url` field that contains the secure download URL.

```json
{
  "url": "https://example.com/api/downloads/token/filename.png"
}
```

**Example:**

```bash
curl -X POST -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT name, address FROM customers"}' \
  "https://app.taleshape.com/api/download/dashboard.json"
```