Dust Datasources API

openapi: 3.0.0
info:
  title: Dust Agents Datasources API
  version: 1.0.2
  description: Manage Dust agent configurations — list, retrieve, update, archive, search, and export agents as YAML.
  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: Datasources
  description: Data sources
paths:
  /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
components:
  schemas:
    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
    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
    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


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dust-tt/refs/heads/main/openapi/dust-tt-datasources-api-openapi.yml