Using the Custom Charts API

The Custom Charts REST API lets you manage your charts, searches, and lists in a programmatic way.

Before you begin

A Jira admin must enable personal access tokens (PAT) to use the API and access its endpoints.

1. Go to the Custom Charts - Settings > Features tab.

2. Enable the Personal Access Tokens feature.

While disabled, users cannot generate tokens and requests to the API will always return a 404 error.

Authenticating with the API

All endpoints require a Custom Charts personal access token (PAT). Use this bearer token in the Authorization header:

Authorization: Bearer <token>

Requests without a valid token return: 401 Unauthorized

Generating a token

When you create a token, it inherits your Jira permissions as its scope. API calls show as performed by the user of the supplied token.

To generate a new PAT:

1. Select :jiraSettings: > General settings.
   You can also use this URL: <jira url>/jira/settings/personal/general.

2. Select Custom Charts - Personal Settings from the sidebar.

3. Enter a Name and set an Expiration, then select Generate token.

Make sure you copy your PAT and save it somewhere safe. You cannot view your token after leaving this page.

Non-working example:

PAT.eyJzdWIiOiI4ODEzMDU6OWMzMjFhZDQtN2I4Zi00ZTIxLWFmMzQtNTFkOGUyYzk3MWFhIiwiYXVkIjoiYXJpOmNsb3VkOmVjb3N5c3RlbTo6aW5zdGFsbGF0aW9uLzdmM2QxYjJhLTk0NGUtNDBjOS1hM2ZkLTY2ZTAxOTgzYjIyMSIsImlhdCI6MTc1NjcyOTYwMCwiZXhwIjoxNzU3MzM0NDAwLCJ0b2tlbklkIjoiZTRmMWM5YjItMzM0ZC00OWU4LWFkYTMtOWQ1MTNiN2VmZDkwIiwicmVnaW9uIjoiZXUifQ.k9Xr2mQpL4vWzYtN8bJhFcRsA1eKuT6oIiDgHnB3ZfX

Accessing the API

The base URL for the Custom Charts API is:

<base-url>/api/custom-charts/1.0

The following types of content are valid for the API:

• Request body (if applicable): Content-Type: application/json

• Response body: application/json

Supported gadgets

The Custom Charts API only works with the following Custom Charts gadgets. Trying to access other Jira apps from the Custom Charts API will return a 404 error for read requests, and a 400 error for write requests.

Error messages

The following error messages may occur while using the Custom Charts API: