Dust
Dust Data Sources API

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.
Dust Data Sources API is one of 9 APIs that Dust publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 2 JSON Schema definitions.
Tagged areas include AI, Artificial Intelligence, Data Sources, Dust, and RAG. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, 1 Naftiko capability spec, and 2 JSON Schemas.
Documentation GitHub OpenAPI
OpenAPI Specification

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
Dust Data Sources API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
