Commonly used Endpoints

Automatically Sync Dot

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

Sync connection with an API token.

post

Authorizations

APIKeyHeaderAPIKeyCookieOAuth2PasswordBearerQueryTokenAuth

X-API-KEYstringRequired

Path parameters

connection_typestringRequired

connection_idstringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/sync/{connection_type}/{connection_id}

HTTPcURLJavaScriptPython

POST /api/sync/{connection_type}/{connection_id} HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

// 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=dot-42673584be9724a21e1550336d6fe509f4a04207461ec9a926ca2a27cbd27fa0

Trigger with dbt webhooks

Call the api endpoint after your dbt run completed.

Webhooks for your jobs | dbt Developer Hubdocs.getdbt.com

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 and overwrite an external asset with an API token.

post

Authorizations

APIKeyHeaderAPIKeyCookieOAuth2PasswordBearerQueryTokenAuth

X-API-KEYstringRequired

Body

application/json

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/import_and_overwrite_external_asset

HTTPcURLJavaScriptPython

POST /api/import_and_overwrite_external_asset HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "external_asset": {
    "id": "text",
    "subtype": "text",
    "folder": "text",
    "name": "text",
    "description": "text",
    "url": "text",
    "active": true,
    "view_count": 0,
    "last_accessed_at": "text",
    "dot_description": "text"
  }
}

No content

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

Authorizations

APIKeyHeaderAPIKeyCookieOAuth2PasswordBearerQueryTokenAuth

X-API-KEYstringRequired

Query parameters

start_datestringOptional

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

end_datestringOptional

by default tomorrow, format YYYY-MM-DD

include_all_workspacesbooleanOptional

Include history from all workspaces (main workspace only)

Default: false

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

get

/api/export_history

HTTPcURLJavaScriptPython

GET /api/export_history HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Ask Dot Automatically

Ask

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

chat_idstringRequired

scopestringOptionalDefault: ""

skip_checkbooleanOptionalDefault: false

extraany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/ask

HTTPcURLJavaScriptPython

POST /api/ask HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "messages": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "chat_id": "text",
  "scope": "",
  "skip_check": false,
  "extra": "text"
}

No content

Ask With History

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

chat_idstringRequired

extraany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/ask_with_history

HTTPcURLJavaScriptPython

POST /api/ask_with_history HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 86

{
  "new_message": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "chat_id": "text",
  "extra": "text"
}

No content

Trigger Deep Analysis

Agentic

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

chat_idstringRequired

skip_checkbooleanOptionalDefault: false

extraany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/agentic

HTTPcURLJavaScriptPython

POST /api/agentic HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "messages": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "chat_id": "text",
  "skip_check": false,
  "extra": "text"
}

No content

User Administration

Get All Users

get

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Responses

200

Successful Response

application/json

Responseany

get

/api/get_users

HTTPcURLJavaScriptPython

GET /api/get_users HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Successful Response

No content

Sendinvitations

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailsstring[]Required

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/send_invitations

HTTPcURLJavaScriptPython

POST /api/send_invitations HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "emails": [
    "text"
  ]
}

No content

Delete User Route

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailstringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/delete_user

HTTPcURLJavaScriptPython

POST /api/delete_user HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "email": "text"
}

No content

Change User Role

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailstringRequired

rolestringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/change_user_role

HTTPcURLJavaScriptPython

POST /api/change_user_role HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "email": "text",
  "role": "text"
}

No content

Add User To Group

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailstringRequired

groupstringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/add_user_to_group

HTTPcURLJavaScriptPython

POST /api/add_user_to_group HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "email": "text",
  "group": "text"
}

No content

Remove User From Group

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailstringRequired

groupstringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/remove_user_from_group

HTTPcURLJavaScriptPython

POST /api/remove_user_from_group HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "email": "text",
  "group": "text"
}

No content

Create User Route

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

emailstringRequired

passwordstringRequired

realnamestringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/create_user

HTTPcURLJavaScriptPython

POST /api/create_user HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "email": "text",
  "password": "text",
  "realname": "text"
}

No content

Automatically Authenticate Embedded Users

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 you enabled this flag on settings: "Allow admins to authenticate for users to enable SSO in embeds".

Get Embedded User Login Token

post

Authorizations

APIKeyHeaderAPIKeyHeaderAPIKeyCookieOAuth2PasswordBearer

X-API-KEYstringRequired

Body

application/json

user_idstringRequired

create_if_not_existsbooleanOptionalDefault: false

groupsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

/api/auth/embedded_user_login

HTTPcURLJavaScriptPython

POST /api/auth/embedded_user_login HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "user_id": "text",
  "create_if_not_exists": false,
  "groups": [
    "text"
  ]
}

No content