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: - type: string - type: number - type: boolean - type: object properties: type: type: string enum: - datetime epoch: type: number truncate: type: boolean description: Whether to truncate existing rows responses: '200': description: The table content: application/json: schema: $ref: '#/components/schemas/Datasource' '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}/tables: get: summary: Get Tables description: Get tables 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 responses: '200': description: The tables content: application/json: schema: type: array items: $ref: '#/components/schemas/Table' '400': description: Invalid request post: summary: Upsert a Table description: Upsert 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 requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Name of the table title: type: string description: Title of the table table_id: type: string description: Unique identifier for the table description: type: string description: Description of the table timestamp: type: number description: Unix timestamp (in milliseconds) for the table (e.g. 1736365559000). tags: type: array items: type: string description: Tags associated with the table mime_type: type: string description: Reserved for internal use, should not be set. Mime type of the table responses: '200': description: The table content: application/json: schema: $ref: '#/components/schemas/Table' '400': description: Invalid request '405': description: Method not supported /api/v1/w/{wId}/spaces/{spaceId}/data_sources: get: summary: Get Data Sources description: Get data sources 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 security: - BearerAuth: [] responses: '200': description: The data sources content: application/json: schema: type: object properties: data_sources: type: array items: $ref: '#/components/schemas/Datasource' '404': description: The workspace was not found '405': description: Method not supported /api/v1/w/{wId}/spaces: get: summary: List Available Spaces. description: Retrieves a list of accessible spaces for the authenticated workspace. tags: - Spaces security: - BearerAuth: [] parameters: - in: path name: wId required: true description: Unique string identifier for the workspace schema: type: string responses: '200': description: Spaces of the workspace content: application/json: schema: type: object properties: spaces: type: array items: $ref: '#/components/schemas/Space' '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. components: schemas: Datasource: type: object properties: id: type: integer description: Unique identifier for the datasource example: 12345 createdAt: type: integer description: Timestamp of when the datasource was created example: 1625097600 name: type: string description: Name of the datasource example: Customer Knowledge Base description: type: string description: Description of the datasource example: Contains all customer-related information and FAQs dustAPIProjectId: type: string description: ID of the associated Dust API project example: 5e9d8c7b6a connectorId: type: string description: ID of the connector used for this datasource example: 1f3e5d7c9b connectorProvider: type: string description: Provider of the connector (e.g., 'webcrawler') example: webcrawler assistantDefaultSelected: type: boolean description: Whether this datasource is selected by default for agents example: true DatasourceView: type: object properties: category: type: string enum: - managed - folder - website - apps description: The category of the data source view createdAt: type: number description: Timestamp of when the data source view was created dataSource: $ref: '#/components/schemas/Datasource' editedByUser: type: object description: The user who last edited the data source view properties: fullName: type: string description: Full name of the user editedAt: type: number description: Timestamp of when the data source view was last edited by the user id: type: number description: Unique identifier for the data source view kind: type: string enum: - default - custom description: The kind of the data source view parentsIn: type: array items: type: string description: List of IDs included in this view, null if complete data source is taken nullable: true sId: type: string description: Unique string identifier for the data source view updatedAt: type: number description: Timestamp of when the data source view was last updated spaceId: type: string description: ID of the space containing the data source view Document: type: object properties: data_source_id: type: string example: 3b7d9f1e5a created: type: number example: 1625097600 document_id: type: string example: 2c4a6e8d0f title: type: string description: Title of the document example: Customer Support FAQ mime_type: type: string description: MIME type of the table example: text/md timestamp: type: number example: 1625097600 tags: type: array items: type: string example: - customer_support - faq parent_id: type: string description: ID of the document parent items: type: string example: 1234f4567c parents: type: array items: type: string example: - 7b9d1f3e5a - 2c4a6e8d0f source_url: type: string nullable: true example: https://example.com/support/article1 hash: type: string example: a1b2c3d4e5 text_size: type: number example: 1024 chunk_count: type: number example: 5 chunks: type: array items: type: object example: - chunk_id: 9f1d3b5a7c text: This is the first chunk of the document. embedding: - 0.1 - 0.2 - 0.3 - 0.4 - chunk_id: 4a2c6e8b0d text: This is the second chunk of the document. embedding: - 0.5 - 0.6 - 0.7 - 0.8 text: type: string example: This is the full text content of the document. It contains multiple paragraphs and covers various topics related to customer support. token_count: type: number nullable: true example: 150 Section: type: object description: A section of a document that can contain nested sections properties: prefix: type: string nullable: true description: Optional prefix text for the section content: type: string nullable: true description: Optional content text for the section sections: type: array items: $ref: '#/components/schemas/Section' description: Array of nested sections Space: type: object properties: sId: type: string description: Unique string identifier for the space name: type: string description: Name of the space kind: type: string enum: - regular - global - system - public description: The kind of the space groupIds: type: array items: type: string description: List of group IDs that have access to the space Table: type: object properties: name: type: string description: Name of the table example: Roi data deprecated: true title: type: string description: Title of the table example: ROI Data table_id: type: string description: Unique identifier for the table example: 1234f4567c description: type: string description: Description of the table example: roi data for Q1 mime_type: type: string description: MIME type of the table example: text/csv schema: type: array description: Array of column definitions items: type: object properties: name: type: string description: Name of the column example: roi value_type: type: string description: Data type of the column enum: - text - int - float - bool - date example: int possible_values: type: array description: Array of possible values for the column (null if unrestricted) items: type: string nullable: true example: - '1' - '2' - '3' timestamp: type: number description: Unix timestamp of table creation/modification example: 1732810375150 tags: type: array description: Array of tags associated with the table items: type: string parent_id: type: string description: ID of the table parent items: type: string example: 1234f4567c parents: type: array description: Array of parent table IDs items: type: string example: - 1234f4567c securitySchemes: BearerAuth: type: http scheme: bearer description: Your DUST API key is a Bearer token.