> For the complete documentation index, see [llms.txt](https://docs.getdot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getdot.ai/developers/api.md).

# API

automate as much as you like

## Everything starts with a token of trust

All API endpoints can be accessed via an API token that is tied to the permissions of a user account. You can also let them expire after some time.

### How to get a token?

1. Go to **Settings / Users**
2. Click **Create New Token**

<figure><img src="https://3709841693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCeRlmJf2y704TpjpubE1%2Fuploads%2FydeWIeEUdeXtgjUUVj0Z%2Fimage.png?alt=media&amp;token=7c25b113-772e-4d07-91c7-3cea67028a4f" alt=""><figcaption></figcaption></figure>

3. **Enter a name**, description, and expiration period
4. **Copy the token** (it's only shown once)

### How to use the token?

You have two ways. You either pass the token as a header with `X-API-KEY` or you pass it as a url parameter in `api_token` . As a header is usually more secure because automated loggers don't store them, but in some places you can't set headers (e.g. dbt webhooks) and then you can use the URL parameter. The older header name `API-KEY` still works, but use `X-API-KEY` for new integrations.

#### Via Headers

Call the user endpoint via command line interface.

```bash
# Basic API request with token
curl -H "X-API-KEY: dot-your_token_here" <https://[app or eu].getdot.ai/api/auth/me>
```

Call the user endpoint via Python.

```python
import requests
headers = {"X-API-KEY": "dot-your_token_here"}
response = requests.get("https://[app or eu].getdot.ai/api/auth/me", headers=headers)
```

#### Via URL - Parameters

For the following endpoints you can also use a URL based authentication:

* Sync connection
* Import external asserts
* Export conversation history

Call the endpoint only via url:

```bash
curl "https://{region}.getdot.ai/api/sync/{connection_type}/{connection_id}" \
     "?user_id={user}&api_token={api_token}"
```

## Evaluate Dot in CI

Use the [evaluation CLI workflow](/developers/api/evaluations-in-ci.md) to run question sets, wait for results, enforce a pass-rate gate, and save JSON/JUnit reports. The [evaluation guide](/train-dot/evaluation.md) explains expected answers and numerical tolerances. For direct API integration, see the [evaluation endpoints](https://test.getdot.ai/redoc#tag/evaluations).

## Learn More

{% content-ref url="/pages/rUXw9XB23uXJ8TSwOjau" %}
[Commonly used Endpoints](/developers/api/commonly-used-endpoints.md)
{% endcontent-ref %}

{% content-ref url="/pages/NcBbF7phunv7RZRZqG7J" %}
[Use Cases and Scripts](/developers/api/use-cases-and-scripts.md)
{% endcontent-ref %}

{% content-ref url="/pages/3R5xLaAuLbOoxqCgtDPH" %}
[All API Endpoints](/developers/api/all-api-endpoints.md)
{% endcontent-ref %}