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` and `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 (default: 24h). For creating permanent dashboards we recommend the 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 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.

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

Response:

The response contains the id of the created dashboard.

{
  "id": "123"
}

Example:

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 (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.

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

Example:

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 (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.

{ 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.

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

Example:

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"