openapi: 3.2.0
info:
  title: Dokki Search API
  version: v1
  summary: 'The programmatic interface to Dokki workspaces: documents, tables, artifacts, files, search, agents, automations, organizations, publishing and account endpoints under https://dokki.one/api/v1.'
  description: Dokki (UEVNS PTE.
  contact:
    name: Dokki support
    email: support@dokki.one
    url: https://dokki.one/pub/docs/faq
  termsOfService: https://dokki.one/terms
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline
  x-generated: '2026-09-19'
  x-source: https://dokki.one/pub/api
  x-provider: dokki-one
servers:
- url: https://dokki.one/api/v1
  description: Production. "All public endpoints use https://dokki.one/api/v1" (https://dokki.one/pub/api/api-conventions); the reference pages state Base URL https://dokki.one with every path prefixed /api/v1, which this document folds into the server URL.
security:
- BearerAuth: []
tags:
- name: Search
  description: Keyword, semantic and hybrid search.
paths:
  /search:
    post:
      operationId: search
      summary: Create search
      tags:
      - Search
      description: 'Create search. Documented at https://dokki.one/pub/api/create-search (required scope: search:read).'
      externalDocs:
        url: https://dokki.one/pub/api/create-search
      x-required-scope: search:read
      x-route-source: app/api/v1/search/route.ts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                mode:
                  type: string
                  enum:
                  - keyword
                  - semantic
                  - hybrid
                workspace_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Upper bound on the search scope, not an authorization grant.
                limit:
                  type: integer
              description: Fields as documented at https://dokki.one/pub/api/search-and-knowledge-graph.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      description: Errors use one stable shape (https://dokki.one/pub/api/pagination-errors-and-rate-limits).
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine code, e.g. unauthorized, insufficient_scope, forbidden.
              examples:
              - unauthorized
              - insufficient_scope
              - forbidden
            message:
              type: string
            request_id:
              type: string
              format: uuid
      examples:
      - error:
          code: forbidden
          message: Resource access denied
          request_id: uuid
    SuccessEnvelope:
      type: object
      description: 'Documented success shape: "Successful responses are JSON. Preserve request_id values and treat resource identifiers as opaque UUIDs."'
      properties:
        data:
          type: object
          additionalProperties: true
        request_id:
          type: string
          description: Request identifier (req_...). Log it and quote it in support tickets.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <credential>. Accepted credentials per https://dokki.one/pub/api/authentication: a Dokki API key (prefix dk_, tenant-bound to Personal or one Org, carrying the x-required-scope of each operation), a Supabase bearer access token, or a browser session. Scopes are API-key scopes, not OAuth scopes; see scopes/dokki-one-scopes.yml.'
externalDocs:
  description: Dokki API documentation
  url: https://dokki.one/pub/api