# Integrations & API

### 1. API Authentication <a href="#api-authentication" id="api-authentication"></a>

All the API calls support authentication with an API key. The application has two types of API keys:

* User API Key: has the same permissions as the user who owns it. Can be found on a user profile page.
* Query API Key: has access only to the query and its results. Can be found on the query page.

Whenever possible we recommend using a Query API key.

### 2. Accessing with Python <a href="#accessing-with-python" id="accessing-with-python"></a>

We provide a light wrapper around the application API called `redash-toolbelt`. It’s a work-in-progress. The source code is hosted on [Github](https://github.com/getredash/redash-toolbelt). The `examples` folder in that repo includes useful demos, such as:

* [Poll for Fresh Query Results (including parameters)](https://github.com/getredash/redash-toolbelt/blob/master/redash_toolbelt/examples/refresh_query.py)
* [Refresh an entire Dashboard](https://github.com/getredash/redash-toolbelt/blob/master/redash_toolbelt/examples/refresh_dashboard.py)
* [Export all your queries as files](https://github.com/getredash/redash-toolbelt/blob/master/redash_toolbelt/examples/query_export.py)

### 3. Common Endpoints <a href="#common-endpoints" id="common-endpoints"></a>

{% hint style="danger" %}
Below is an incomplete list of API endpoints. These may change in future versions of the application.
{% endhint %}

Each endpoint is appended to your application's base URL. For example:

* `https://app.redash.io/<slug>`
* `https://redash.example.com`

#### i. Queries <a href="#queries" id="queries"></a>

`/api/queries`

* GET: Returns a paginated array of query objects.
  * Includes the most recent `query_result_id` for non-parameterized queries.
* POST: Create a new query object

`/api/queries/<id>`

* GET: Returns an individual query object
* POST: Edit an existing query object.
* DELETE: Archive this query.

`/api/queries/<id>/results`

* GET: Get a cached result for this query ID.
  * Only works for non parameterized queries. If you attempt to GET results for a parameterized query you’ll receive the error: `no cached result found for this query`. See POST instructions for this endpoint to get results for parameterized queries.
* POST: Initiates a new query execution or returns a cached result.
  * The API prefers to return a cached result. If a cached result is not available then a new execution job begins and the job object is returned. To bypass a stale cache, include a `max_age` key which is an integer number of seconds. If the cached result is older than `max_age`, the cache is ignored and a new execution begins. If you set `max_age` to `0` this guarantees a new execution.
  * If passing parameters, they must be included in the JSON request body as a `parameters` object.

{% hint style="info" %}

```json
//Here’s an example JSON object including different parameter types:
{ 
    "parameters": {
    	"number_param": 100,
    	"date_param": "2020-01-01",
    	"date_range_param": {
    		"start": "2020-01-01",
    		"end": "2020-12-31"
    		}
    	},
      "max_age": 1800
    }
}
```

{% endhint %}

#### ii. Jobs <a href="#jobs" id="jobs"></a>

`/api/jobs/<job_id>`

* GET: Returns a query task result (job)
  * Possible statuses:
    * 1 == PENDING (waiting to be executed)
    * 2 == STARTED (executing)
    * 3 == SUCCESS
    * 4 == FAILURE
    * 5 == CANCELLED
  * When status is success, the job will include a `query_result_id`

#### iii. Query Results <a href="#query-results" id="query-results"></a>

`/api/query_results/<query_result_id>`

* GET: Returns a query result
  * Appending a filetype of `.csv` or `.json` to this request will return a downloadable file. If you append your `api_key` in the query string, this link will work for non-logged-in users.

#### iv. Dashboards <a href="#dashboards" id="dashboards"></a>

`/api/dashboards`

* GET: Returns a paginated array of dashboard objects.
* POST: Create a new dashboard object

`/api/dashboards/<dashboard_slug>`

* GET: Returns an individual dashboard object.
* DELETE: Archive this dashboard

`/api/dashboards/<dashboard_id>`

* POST: Edit an existing dashboard object.