openapi: 3.0.0
info:
  title: Dust Search API
  version: 1.0.2
  description: Search nodes (documents, tables, conversations) across a workspace with optional streaming.
  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: Search
  description: Search
paths:
  /api/v1/w/{wId}/search:
    get:
      summary: Search for Nodes in the Workspace (streaming)
      description: Search for nodes in the workspace with SSE streaming
      tags:
      - Search
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      - in: query
        name: query
        required: true
        description: The search query (minimum 3 characters)
        schema:
          type: string
      - in: query
        name: limit
        required: false
        description: Number of results per page (1-100, default 25)
        schema:
          type: integer
      - in: query
        name: cursor
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - in: query
        name: viewType
        required: false
        description: Type of view to filter results
        schema:
          type: string
          enum:
          - all
          - document
          - table
      - in: query
        name: spaceIds
        required: false
        description: Comma-separated list of space IDs to search in
        schema:
          type: string
      - in: query
        name: includeDataSources
        required: false
        description: Whether to include data sources
        schema:
          type: boolean
      - in: query
        name: searchSourceUrls
        required: false
        description: Whether to search source URLs
        schema:
          type: boolean
      - in: query
        name: includeTools
        required: false
        description: Whether to include tool results
        schema:
          type: boolean
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Search results streamed successfully
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '405':
          description: Method not allowed
    post:
      summary: Search for Nodes in the Workspace
      description: Search for nodes in the workspace
      tags:
      - Search
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  description: The search query
                includeDataSources:
                  type: boolean
                  description: List of data source IDs to include in search
                viewType:
                  type: string
                  description: Type of view to filter results
                spaceIds:
                  type: array
                  description: List of space IDs to search in
                  items:
                    type: string
                nodeIds:
                  type: array
                  description: List of specific node IDs to search
                  items:
                    type: string
                searchSourceUrls:
                  type: boolean
                  description: Whether to search source URLs
      responses:
        '200':
          description: Search results retrieved successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Space not found
        '405':
          description: Method not allowed
  /api/v1/w/{wId}/search/tools/upload:
    post:
      summary: Upload a Tool File
      description: Download and upload a file from a tool (MCP server) to Dust
      tags:
      - Search
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serverViewId
              - externalId
              properties:
                serverViewId:
                  type: string
                  description: The MCP server view ID
                externalId:
                  type: string
                  description: The external ID of the file in the tool
                conversationId:
                  type: string
                  description: Optional conversation ID for context
                serverName:
                  type: string
                  description: Optional name of the MCP server (e.g., "Notion", "GitHub")
                serverIcon:
                  type: string
                  description: Optional icon identifier for the MCP server
      responses:
        '200':
          description: File uploaded successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '405':
          description: Method not allowed
        '500':
          description: Internal server error
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Your DUST API key is a Bearer token.