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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inverse.watch/admin-and-dev-guide/integrations-and-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.