Tables

On this page we'll dive into the Tables endpoint you can use to manage Data Sources' Tables programmatically. Tables let you insert tabular data that can be queried by an assistant using the Query Tables action (Generates a SQL query that is then run on your tabular data and whose results are presented to the assistant to generate its reply).

Authentication

All requests to the Dust API must be authenticated using an Authentication header. The value of this header must be the string Bearer followed by a space and your API key. You can find your API key in your account's API keys panel.

The Column model

The Column model represents a column in a Data Source Table, in particular its name and value type.

Properties

Name
name
Type
string
Description
The name of the colunn.
Name
value_type
Type
string
Description
The type of the column, one of int, float, text.
Name
possible_values
Type
string[]
Description
If the cardinality of the column is low, the possible values of the column.

The Table model

The Table model represents a Data Source Table.

Properties

Name
table_id
Type
string
Description
The table ID as specified or generated at creation.
Name
table_name
Type
string
Description
The table name as specified at creation.
Name
description
Type
string
Description
The description of the table (used by the model to generate SQL queries).
Name
schema
Type
Column[]
Description
The schema of the table as specified at data upload.

POST/v1/w/:workspace_id/data_sources/:data_source_name/tables

Create a Table

This endpoint enables you to create a new Table within an existing Data Source. Table name must be unique within the Data Source.

URL attributes

Name
workspace_id
Type
string
Description
The ID of your workspace (can be found in the Data Source's URL)
Name
data_source_name
Type
string
Description
The name of the Data Source you want to add a Table to.

JSON body attributes

Attributes are passed as a JSON object in the request body.

Name
name
Type
string
Description
The name of the Table to create (must be unique within a Data Source).
Name
description
Type
string
Description
The description of the Table (used by the model to generate SQL queries).

Optional JSON body attributes

Name
table_id
Type
string
Description
A unique ID for the Table. If not specified, a random unique ID will be generated.

Request

POST

/v1/w/:workspace_id/data_sources/:data_source_name/tables

curl https://dust.tt/api/v1/w/3e26b0e764/data_sources/foo/tables \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customers",
    "description": "Table containing our customer data."
  }'

Response

{
  "table": {
    "data_source_id": "foo",
    "created":1709127589841,
    "table_id":"015001320f",
    "name":"customers",
    "description":"Table containing our customer data.",
    "schema":null
  }
}

GET/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id

Retrieve a Table

This endpoint enables you to retrieve a Table by ID.

URL attributes

Name
workspace_id
Type
string
Description
The ID of your workspace (can be found in the Data Source's URL)
Name
data_source_name
Type
string
Description
The name of the Data Source you want to retrieve the Table from.
Name
table_id
Type
string
Description
The ID of the Table you want to retrieve.

Request

GET

/v1/w/:workspace_id/data_sources/:data_source_name/talbes/:table_id

curl https://dust.tt/api/v1/w/3e26b0e764/data_sources/foo/tables/015001320f \
  -H "Authorization: Bearer sk-..."

Response

{
  "table": {
    "data_source_id": "foo",
    "created":1709127589841,
    "table_id":"015001320f",
    "name":"customers",
    "description":"Table containing our customer data.",
    "schema":null
  }
}

POST/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows

Upsert Rows

This endpoint enables you to add or update rows to an existing Table. Rows are JSON objects associating keys to values. The keys and value types (string, number, boolean, datetime) must match the Table's schema. New tables don't have a schema and will infer it from the first rows inserted.

URL attributes

Name
workspace_id
Type
string
Description
The ID of your workspace (can be found in the Data Source's URL)
Name
data_source_name
Type
string
Description
The name of the Data Source of the Table you want to upsert Rows to.
Name
table_id
Type
string
Description
The ID of the Table you want to upsert Rows to.

Row JSON attributes

Attributes are passed as a JSON object in the request body.

Name
row_id
Type
string
Description
A unique ID for the row. It should be unique within the Table and must be specified. You can use a UUID or an incremented integer passed as string. It is used to let you update rows. If you post a row with an existing row_id, the row will be updated.
Name
value
Type
{[key: string]: string | number | boolean | null}
Description
The value of the row.

JSON body attributes

Attributes are passed as a JSON object in the request body.

Name
rows
Type
Row[]
Description
The rows to upsert (based on their row_id).

Optional JSON body attributes

Name
truncate
Type
boolean
Description
If true the content of the Table is erased and replaced by the new rows. Otherwise rows are upserted to the Table.

Request

POST

/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows

curl https://dust.tt/api/v1/w/3e26b0e764/data_sources/foo/tables/015001320f/rows \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
 -d '{
   "rows": [
     {
       "row_id": "1",
       "value": { "name": "John", "conversations": 129, "paying": true }
     }, {
       "row_id": "2",
       "value": { "name": "Mark", "conversations": 3, "paying": false }
     }, {
       "row_id": "3",
       "value": { "name": "Sally", "conversations": 456, "paying": true }
     }
   ],
   "truncate": false,
 }'

Response

{
  "table": {
    "name": "customers",
    "table_id":"015001320f",
    "description":"Table containing our customer data.",
    "schema": [
      {"name": "name", "value_type": "text", "possible_values": ["\"Sally\"", "\"John\"", "\"Mark\""]},
      {"name": "conversations", "value_type":"int", "possible_values": ["456", "129", "3"]},
      {"name": "paying", "value_type": "bool", "possible_values": ["TRUE", "FALSE"]}
    ]
  }
}

GET/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows

List Rows

This endpoint enables you to list the rows of a table

URL attributes

Name
workspace_id
Type
string
Description
The ID of your workspace (can be found in the Data Source's URL)
Name
data_source_name
Type
string
Description
The name of the Data Source of the Table.
Name
table_id
Type
string
Description
The ID of the Table you want list Rows from.

Required Query parameters

Query attributes are passed as GET parameters.

Name
offset
Type
integer
Description
The offset to use to retrieve the rows, for paging.
Name
limit
Type
integer
Description
The maximum number of rows to retrieve, for paging.

Request

GET

/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows

curl "https://dust.tt/api/v1/w/3e26b0e764/data_sources/foo/tables/015001320f/rows?offset=0&limit=10" \
  -H "Authorization: Bearer sk-..."

Response

{
  "rows": [
    {
      "row_id": "1",
      "value": { "name": "John", "conversations": 129, "paying": true }
    }, {
      "row_id": "2",
      "value": { "name": "Mark", "conversations": 3, "paying": false }
    }, {
      "row_id":"3",
      "value": { "name": "Sally", "conversations": 456, "paying": true }
    }
  ],
  "offset": 0,
  "limit": 10,
  "total": 3
}

DELETE/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows/:row_id

Delete Rows

This endpoint enables you to delete a particular row from a table.

URL attributes

Name
workspace_id
Type
string
Description
The ID of your workspace (can be found in the Data Source's URL)
Name
data_source_name
Type
string
Description
The name of the Data Source of the Table you want to delete a Row from.
Name
table_id
Type
string
Description
The ID of the Table from which you want to delete a Row.
Name
row_id
Type
string
Description
The ID of the Row you want to delete.

Request

DELETE

/v1/w/:workspace_id/data_sources/:data_source_name/tables/:table_id/rows/:row_id

curl -XDELETE "https://dust.tt/api/v1/w/3e26b0e764/data_sources/foo/tables/015001320f/rows/1" \
  -H "Authorization: Bearer sk-..."

Response

{
  "sucess": true
}