API

automate as much as you like

Automatically Sync Dot

To keep Dot in sync with your production environment, it is recommended to trigger the following API endpoint

Sync Connection

post

Path parameters

connection_typestringrequired

connection_idstringrequired

Query parameters

user_idstringrequired

api_tokenstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/sync/{connection_type}/{connection_id}?user_id=text&api_token=text'

200

422

200

No body

Successful Response

// URL endpoint
https://{region}.getdot.ai/api/sync/{connection_type}/{connection_type}?user_id={user}&api_token={api_token}

• Region: app (US) or eu (EU)

• Connection Type: postgres, redshift, snowflake, mssql, bigquery, databricks, looker, dbt

• User ID: usually email of the user (url encoded)

• API Token: can get created (and overwritten) by clicking Copy API Token in Settings/Users/Actions/···

Trigger with curl (CLI)

curl -X "POST" "https://eu.getdot.ai/api/sync/bigquery/my-bg-id?user_id=sync_user%40contoso.com&api_token=42673584be9724a21e1550336d6fe509f4a04207461ec9a926ca2a27cbd27fa0

Trigger with dbt webhooks

Call the api endpoint after your dbt run completed.

Webhooks for your jobs | dbt Developer Hub

Documentation how to setup a dbt webhooks

Import External Assets

Inform Dot about key external knowledge assets, such as BI dashboards or custom data apps, so it can recommend them to users and assist with discovery and understanding. Authentication works similarly to the Sync Connection endpoint.

Import External Asset

post

Query parameters

user_idstringrequired

api_tokenstringrequired

Body

external_assetobjectrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/import_and_overwrite_external_asset?user_id=text&api_token=text' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_asset": {
      "id": "text",
      "subtype": "text",
      "folder": "text",
      "name": "text",
      "description": "text",
      "url": "text",
      "active": true,
      "view_count": 1,
      "last_accessed_at": "text",
      "dot_description": "text"
    }
  }'

200

422

200

No body

Successful Response

Export Conversation History

Export all conversations together with relevant meta data fields such as number of messages or author.

Get all historical chat messages.

get

Query parameters

user_idstringrequired

api_tokenstringrequired

start_datestringoptional

by default two weeks ago, format YYYY-MM-DD

end_datestringoptional

by default tomorrow, format YYYY-MM-DD

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/export_history?user_id=text&api_token=text'

200

422

200

No body

Successful Response

Authentication for all other endpoints

For most operations on Dot you first need to login.

Example of Python script to authenticate and adding a label to a chat

import requests
import json

# Configuration
BASE_URL = "https://app.getdot.ai"
LOGIN_ENDPOINT = "/api/auth/token"
ADD_LABEL_ENDPOINT = "/api/add_label_to_chat"

# Replace these with your actual credentials and chat details
USERNAME = "your_username"
PASSWORD = "your_password"
CHAT_ID = "your_chat_id"
LABELS = ["your_label"]

def authenticate():
    """Authenticate and get access token."""
    data = {
        "grant_type": "password",
        "username": USERNAME,
        "password": PASSWORD
    }
    
    try:
        response = requests.post(f"{BASE_URL}{LOGIN_ENDPOINT}", data=data)
        response.raise_for_status()
        return response.json().get("access_token")
    except requests.exceptions.RequestException as e:
        print(f"Authentication failed: {e}")
        return None

def add_label_to_chat(access_token, chat_id, labels):
    """Add labels to a chat."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    data = {
        "chat_id": chat_id,
        "labels": labels
    }
    
    try:
        response = requests.post(
            f"{BASE_URL}{ADD_LABEL_ENDPOINT}",
            headers=headers,
            json=data
        )
        response.raise_for_status()
        print("Successfully added labels to chat.")
    except requests.exceptions.RequestException as e:
        print(f"Failed to add labels to chat: {e}")

def main():
    access_token = authenticate()
    if access_token:
        add_label_to_chat(access_token, CHAT_ID, LABELS)

if __name__ == "__main__":
    main()

Login For Access Token

post

Body

grant_typestringoptional

Pattern: password

usernamestringrequired

passwordstringrequired

scopestring · default: ""optional

client_idstringoptional

client_secretstringoptional

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=text&username=text&password=text&scope=text&client_id=text&client_secret=text'

200

422

200

No body

Successful Response

For embedded use cases that require SSO, where your end users have individual permissions you can use this endpoint to obtain an access token for users that is valid for 24h. Here is an example on how you can use it to embed Dot in your application.

Please make sure that enabled this flag on settings: "Allow admins to authenticate for users to enable SSO in embeds".

Get Embedded User Login Token

post

Authorizations

Body

user_idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/auth/embedded_user_login' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "text"
  }'

200

422

200

No body

Successful Response

User Administration

Get All Users

get

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/get_users'

200

200

No body

Successful Response

Sendinvitations

post

Authorizations

Body

emailsstring[]required

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/send_invitations' \
  --header 'Content-Type: application/json' \
  --data '{
    "emails": [
      "text"
    ]
  }'

200

422

200

No body

Successful Response

Delete User Route

post

Authorizations

Body

emailstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/delete_user' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "text"
  }'

200

422

200

No body

Successful Response

Change User Role

post

Authorizations

Body

emailstringrequired

rolestringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/change_user_role' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "text",
    "role": "text"
  }'

200

422

200

No body

Successful Response

Add User To Group

post

Authorizations

Body

emailstringrequired

groupstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/add_user_to_group' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "text",
    "group": "text"
  }'

200

422

200

No body

Successful Response

Remove User From Group

post

Authorizations

Body

emailstringrequired

groupstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/remove_user_from_group' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "text",
    "group": "text"
  }'

200

422

200

No body

Successful Response

Create User Route

post

Authorizations

Body

emailstringrequired

passwordstringrequired

realnamestringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/create_user' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "text",
    "password": "text",
    "realname": "text"
  }'

200

422

200

No body

Successful Response

Ask questions

Ask With History

post

Authorizations

Body

new_messageobjectrequired

chat_idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/ask_with_history' \
  --header 'Content-Type: application/json' \
  --data '{
    "new_message": {},
    "chat_id": "text"
  }'

200

422

200

No body

Successful Response

Ask

post

Authorizations

Body

messagesobject[]required

chat_idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/ask' \
  --header 'Content-Type: application/json' \
  --data '{
    "messages": [
      {}
    ],
    "chat_id": "text"
  }'

200

422

200

No body

Successful Response