Manage Dust data sources, data source views, spaces, documents, tables, and folders. Upsert documents and table rows programmatically, search semantically, manage hierarchies and parents, and check the asynchronous upsert queue. Data sources are the retrieval layer behind every Dust agent.
openapi: 3.0.0
info:
title: Dust Data Sources API
version: 1.0.2
description: Upsert, search, and manage documents, tables, and folders inside Dust data sources and data source views, organized
into workspace spaces.
contact:
name: Dust Support
url: https://docs.dust.tt
license:
name: MIT
url: https://github.com/dust-tt/dust/blob/main/LICENSE
servers:
- url: https://dust.tt
description: Dust.tt API (us-central1)
- url: https://eu.dust.tt
description: Dust.tt API (europe-west1)
tags:
- name: DatasourceViews
description: Data source views
- name: Datasources
description: Data sources
- name: Spaces
description: Spaces
paths:
/api/v1/w/{wId}/spaces/{spaceId}/data_source_views/{dsvId}:
get:
tags:
- DatasourceViews
security:
- BearerAuth: []
summary: Get a Data Source View
parameters:
- name: wId
in: path
required: true
schema:
type: string
- name: spaceId
in: path
required: true
schema:
type: string
- name: dsvId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DatasourceView'
'404':
description: Data source view not found
'405':
description: Method not allowed
patch:
tags:
- DatasourceViews
security:
- BearerAuth: []
summary: Update a Data Source View
parameters:
- name: wId
in: path
required: true
schema:
type: string
- name: spaceId
in: path
required: true
schema:
type: string
- name: dsvId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
oneOf:
- type: object
properties:
parentsIn:
type: array
items:
type: string
required:
- parentsIn
- type: object
properties:
parentsToAdd:
type: array
items:
type: string
parentsToRemove:
type: array
items:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DatasourceView'
'400':
description: Invalid request body
'403':
description: Unauthorized - Only admins or builders can administrate spaces
'404':
description: Data source view not found
'405':
description: Method not allowed
'500':
description: Internal server error - The data source view cannot be updated
delete:
tags:
- DatasourceViews
security:
- BearerAuth: []
summary: Delete a Data Source View
parameters:
- name: wId
in: path
required: true
schema:
type: string
- name: spaceId
in: path
required: true
schema:
type: string
- name: dsvId
in: path
required: true
schema:
type: string
responses:
'204':
description: Data source view successfully deleted
'401':
description: Unauthorized - The data source view is in use and cannot be deleted
'403':
description: Forbidden - Only admins or builders can delete data source views
'404':
description: Data source view not found
'405':
description: Method not allowed
/api/v1/w/{wId}/spaces/{spaceId}/data_source_views/{dsvId}/search:
get:
summary: Search the Data Source View
description: Search the data source view identified by {dsvId} in the workspace identified by {wId}.
tags:
- DatasourceViews
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsvId
required: true
description: ID of the data source view
schema:
type: string
- in: query
name: query
required: true
description: The search query
schema:
type: string
- in: query
name: top_k
required: true
description: The number of results to return
schema:
type: number
- in: query
name: full_text
required: true
description: Whether to return the full document content
schema:
type: boolean
- in: query
name: target_document_tokens
required: false
description: The number of tokens in the target document
schema:
type: number
- in: query
name: timestamp_gt
required: false
description: The timestamp to filter by
schema:
type: number
- in: query
name: timestamp_lt
required: false
description: The timestamp to filter by
schema:
type: number
- in: query
name: tags_in
required: false
description: The tags to filter by
schema:
type: string
- in: query
name: tags_not
required: false
description: The tags to filter by
schema:
type: string
- in: query
name: parents_in
required: false
description: The parents to filter by
schema:
type: string
- in: query
name: parents_not
required: false
description: The parents to filter by
schema:
type: string
responses:
'200':
description: The documents
content:
application/json:
schema:
type: object
properties:
documents:
type: array
items:
type: object
properties:
id:
type: string
description: ID of the document
title:
type: string
description: Title of the document
content:
type: string
description: Content of the document
tags:
type: array
items:
type: string
description: Tags of the document
parents:
type: array
items:
type: string
description: Parents of the document
timestamp:
type: number
description: Timestamp of the document
data:
type: object
description: Data of the document
score:
type: number
description: Score of the document
'400':
description: Invalid request error
'405':
description: Method not supported error
/api/v1/w/{wId}/spaces/{spaceId}/data_source_views:
get:
summary: List Data Source Views
description: Retrieves a list of data source views for the specified space
tags:
- DatasourceViews
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
responses:
'200':
description: List of data source views in the space
content:
application/json:
schema:
type: object
properties:
dataSourceViews:
type: array
items:
$ref: '#/components/schemas/DatasourceView'
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'404':
description: Workspace not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/check_upsert_queue:
get:
summary: Check the Upsert Queue Status for a Data Source
description: Returns the number of running document upsert workflows for this data source. This endpoint is only accessible
with system API keys (e.g., from connectors).
tags:
- Datasources
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
security:
- BearerAuth: []
responses:
'200':
description: Status of the upsert queue
content:
application/json:
schema:
type: object
properties:
running_count:
type: number
description: Number of currently running upsert workflows
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. Only system keys can access this endpoint.
'404':
description: Data source not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents/{documentId}:
get:
summary: Retrieve a Document from a Data Source
description: Retrieve a document from a data source identified by {dsId} in the workspace identified by {wId}.
tags:
- Datasources
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: documentId
required: true
description: ID of the document
schema:
type: string
security:
- BearerAuth: []
responses:
'200':
description: The document
content:
application/json:
schema:
type: object
properties:
document:
$ref: '#/components/schemas/Document'
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'404':
description: Data source or document not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
post:
summary: Upsert a Document in a Data Source
description: Upsert a document in a data source in the workspace identified by {wId}.
tags:
- Datasources
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: documentId
required: true
description: ID of the document
schema:
type: string
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The title of the document to upsert.
mime_type:
type: string
description: The MIME type of the document to upsert.
text:
type: string
description: The text content of the document to upsert.
section:
$ref: '#/components/schemas/Section'
source_url:
type: string
description: The source URL for the document to upsert.
tags:
type: array
items:
type: string
description: Tags to associate with the document.
timestamp:
type: number
description: Unix timestamp (in milliseconds) for the document (e.g. 1736365559000).
light_document_output:
type: boolean
description: If true, a lightweight version of the document will be returned in the response (excluding
the text, chunks and vectors). Defaults to false.
async:
type: boolean
description: If true, the upsert operation will be performed asynchronously.
upsert_context:
type: object
description: Additional context for the upsert operation.
responses:
'200':
description: The document
content:
application/json:
schema:
type: object
properties:
document:
$ref: '#/components/schemas/Document'
data_source:
$ref: '#/components/schemas/Datasource'
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. The data source is managed.
'404':
description: Data source or document not found.
'405':
description: Method not supported.
'429':
description: Rate limit exceeded.
'500':
description: Internal Server Error.
delete:
summary: Delete a Document from a Data Source
description: Delete a document from a data source in the workspace identified by {wId}.
tags:
- Datasources
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: documentId
required: true
description: ID of the document
schema:
type: string
security:
- BearerAuth: []
responses:
'200':
description: The document
content:
application/json:
schema:
type: object
properties:
document:
type: object
properties:
document_id:
type: string
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. The data source is managed.
'404':
description: Data source or document not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents/{documentId}/parents:
post:
summary: Update the Parents of a Document
description: Update the parents of a document in the data source identified by {dsId} in the workspace identified by
{wId}.
tags:
- Datasources
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: documentId
required: true
description: ID of the document
schema:
type: string
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
parent_id:
type: string
description: Direct parent ID of the document
parents:
type: array
items:
type: string
description: 'Document and ancestor ids, with the following convention: parents[0] === documentId, parents[1]
=== parentId, and then ancestors ids in order'
responses:
'200':
description: The parents were updated
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'404':
description: Data source or workspace not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents:
get:
summary: Get Documents
description: Get documents in the data source identified by {dsId} in the workspace identified by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: query
name: document_ids
description: The IDs of the documents to fetch (optional)
schema:
type: array
items:
type: string
- in: query
name: limit
description: Limit the number of documents returned
schema:
type: integer
- in: query
name: offset
description: Offset the returned documents
schema:
type: integer
responses:
'200':
description: The documents
content:
application/json:
schema:
type: object
properties:
documents:
type: array
items:
$ref: '#/components/schemas/Document'
total:
type: integer
'404':
description: The data source was not found
'405':
description: Method not supported
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/search:
get:
summary: Search the Data Source
description: Search the data source identified by {dsId} in the workspace identified by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: ID of the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: query
name: query
required: true
description: The search query
schema:
type: string
- in: query
name: top_k
required: true
description: The number of results to return
schema:
type: number
- in: query
name: full_text
required: true
description: Whether to return the full document content
schema:
type: boolean
- in: query
name: target_document_tokens
required: false
description: The number of tokens in the target document
schema:
type: number
- in: query
name: timestamp_gt
required: false
description: The timestamp to filter by
schema:
type: number
- in: query
name: timestamp_lt
required: false
description: The timestamp to filter by
schema:
type: number
- in: query
name: tags_in
required: false
description: The tags to filter by
schema:
type: string
- in: query
name: tags_not
required: false
description: The tags to filter by
schema:
type: string
- in: query
name: parents_in
required: false
description: The parents to filter by
schema:
type: string
- in: query
name: parents_not
required: false
description: The parents to filter by
schema:
type: string
responses:
'200':
description: The documents
content:
application/json:
schema:
type: object
properties:
documents:
type: array
items:
type: object
properties:
id:
type: string
description: ID of the document
title:
type: string
description: Title of the document
content:
type: string
description: Content of the document
tags:
type: array
items:
type: string
description: Tags of the document
parents:
type: array
items:
type: string
description: Parents of the document
timestamp:
type: number
description: Timestamp of the document
data:
type: object
description: Data of the document
score:
type: number
description: Score of the document
'400':
description: Invalid request error
'405':
description: Method not supported error
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}:
get:
summary: Get a Table
description: Get a table in the data source identified by {dsId} in the workspace identified by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
responses:
'200':
description: The table
content:
application/json:
schema:
$ref: '#/components/schemas/Table'
'404':
description: The table was not found
'405':
description: Method not supported
delete:
summary: Delete a Table
description: Delete a table in the data source identified by {dsId} in the workspace identified by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
responses:
'200':
description: The table was deleted
'404':
description: The table was not found
'405':
description: Method not supported
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}/rows/{rId}:
get:
summary: Get a Row
description: Get a row in the table identified by {tId} in the data source identified by {dsId} in the workspace identified
by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
- in: path
name: rId
required: true
description: ID of the row
schema:
type: string
responses:
'200':
description: The row
content:
application/json:
schema:
$ref: '#/components/schemas/Datasource'
'404':
description: The row was not found
'405':
description: Method not supported
delete:
summary: Delete a Row
description: Delete a row in the table identified by {tId} in the data source identified by {dsId} in the workspace
identified by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
- in: path
name: rId
required: true
description: ID of the row
schema:
type: string
responses:
'200':
description: The row was deleted
'404':
description: The row was not found
'405':
description: Method not supported
/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}/rows:
get:
summary: List Rows
description: List rows in the table identified by {tId} in the data source identified by {dsId} in the workspace identified
by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
- in: query
name: limit
description: Limit the number of rows returned
schema:
type: integer
- in: query
name: offset
description: Offset the returned rows
schema:
type: integer
responses:
'200':
description: The rows
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Datasource'
'405':
description: Method not supported
post:
summary: Upsert Rows
description: Upsert rows in the table identified by {tId} in the data source identified by {dsId} in the workspace identified
by {wId}.
tags:
- Datasources
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: dsId
required: true
description: ID of the data source
schema:
type: string
- in: path
name: tId
required: true
description: ID of the table
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rows:
type: array
items:
type: object
properties:
row_id:
type: string
description: Unique identifier for the row
value:
type: object
additionalProperties:
oneOf:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dust-tt/refs/heads/main/openapi/dust-datasources-api-openapi.yml