openapi: 3.1.0
info:
  title: Couchbase Search Service REST API
  description: >-
    The Couchbase Search Service REST API allows developers to create, manage,
    and query Full Text Indexes on Couchbase Server. It supports full-text
    search queries with features like fuzzy matching, faceted search,
    highlighting, and geospatial queries. The API provides endpoints for
    index definition, index management, and executing search queries across
    JSON documents stored in Couchbase buckets.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
  description: Couchbase Search Service REST API Documentation
  url: https://docs.couchbase.com/server/current/rest-api/rest-fts.html
servers:
  - url: https://localhost:8094
    description: Search Service (default port)
  - url: https://localhost:18094
    description: Search Service (SSL)
tags:
  - name: Search Indexes
    description: >-
      Endpoints for creating, retrieving, updating, and deleting Full Text
      Search index definitions.
  - name: Search Monitoring
    description: >-
      Endpoints for monitoring search index statistics and service status.
  - name: Search Queries
    description: >-
      Endpoints for executing full-text search queries against search indexes.
security:
  - basicAuth: []
paths:
  /api/index:
    get:
      operationId: listSearchIndexes
      summary: List all search index definitions
      description: >-
        Returns the definitions of all Full Text Search indexes configured
        on the cluster, including their type mappings, analyzers, and
        configuration parameters.
      tags:
        - Search Indexes
      responses:
        '200':
          description: Successful retrieval of search index list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIndexList'
        '401':
          description: Unauthorized access
  /api/index/{indexName}:
    get:
      operationId: getSearchIndex
      summary: Get a search index definition
      description: >-
        Returns the definition of a specific Full Text Search index including
        its type mappings, analyzers, and configuration parameters.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
      responses:
        '200':
          description: Successful retrieval of search index definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIndexResponse'
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
    put:
      operationId: createOrUpdateSearchIndex
      summary: Create or update a search index
      description: >-
        Creates a new Full Text Search index or updates an existing one with
        the provided index definition. The index name in the URL must match
        the name in the request body.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchIndexDefinition'
      responses:
        '200':
          description: Index created or updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Operation status
        '400':
          description: Invalid index definition
        '401':
          description: Unauthorized access
    delete:
      operationId: deleteSearchIndex
      summary: Delete a search index
      description: >-
        Deletes the specified Full Text Search index and all associated data.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
      responses:
        '200':
          description: Index deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/index/{indexName}/count:
    get:
      operationId: getSearchIndexDocCount
      summary: Get document count for a search index
      description: >-
        Returns the number of documents that have been indexed by the
        specified Full Text Search index.
      tags:
        - Search Monitoring
      parameters:
        - $ref: '#/components/parameters/indexName'
      responses:
        '200':
          description: Successful retrieval of document count
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Response status
                  count:
                    type: integer
                    description: Number of indexed documents
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/index/{indexName}/query:
    post:
      operationId: querySearchIndex
      summary: Query a search index
      description: >-
        Executes a full-text search query against the specified index. Supports
        various query types including match, term, phrase, boolean, numeric
        range, date range, geospatial, and conjunction/disjunction queries.
        Results include relevance scores, highlighting, and faceted results.
      tags:
        - Search Queries
      parameters:
        - $ref: '#/components/parameters/indexName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQueryRequest'
      responses:
        '200':
          description: Search query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchQueryResult'
        '400':
          description: Invalid search query
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/index/{indexName}/ingestControl/{operation}:
    post:
      operationId: controlSearchIndexIngest
      summary: Control search index data ingestion
      description: >-
        Pauses or resumes data ingestion (DCP mutations) for the specified
        search index.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
        - name: operation
          in: path
          required: true
          description: The ingestion control operation to perform
          schema:
            type: string
            enum:
              - pause
              - resume
      responses:
        '200':
          description: Ingestion control operation successful
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/index/{indexName}/queryControl/{operation}:
    post:
      operationId: controlSearchIndexQuery
      summary: Control search index query access
      description: >-
        Allows or disallows queries on the specified search index.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
        - name: operation
          in: path
          required: true
          description: The query control operation to perform
          schema:
            type: string
            enum:
              - allow
              - disallow
      responses:
        '200':
          description: Query control operation successful
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/index/{indexName}/planFreezeControl/{operation}:
    post:
      operationId: controlSearchIndexPlanFreeze
      summary: Control search index plan freeze
      description: >-
        Freezes or unfreezes the assignment of index partitions to nodes.
      tags:
        - Search Indexes
      parameters:
        - $ref: '#/components/parameters/indexName'
        - name: operation
          in: path
          required: true
          description: The plan freeze control operation
          schema:
            type: string
            enum:
              - freeze
              - unfreeze
      responses:
        '200':
          description: Plan freeze control operation successful
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/stats:
    get:
      operationId: getSearchStats
      summary: Get search service statistics
      description: >-
        Returns aggregate statistics for the Search service and all indexes
        on the node.
      tags:
        - Search Monitoring
      responses:
        '200':
          description: Successful retrieval of search statistics
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized access
  /api/stats/index/{indexName}:
    get:
      operationId: getSearchIndexStats
      summary: Get statistics for a search index
      description: >-
        Returns detailed statistics for a specific search index including
        document count, mutation throughput, and query performance metrics.
      tags:
        - Search Monitoring
      parameters:
        - $ref: '#/components/parameters/indexName'
      responses:
        '200':
          description: Successful retrieval of index statistics
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
  /api/nsstats:
    get:
      operationId: getSearchNamespaceStats
      summary: Get namespace-level search statistics
      description: >-
        Returns namespace-level statistics for the Search service that can
        be consumed by monitoring systems like Prometheus.
      tags:
        - Search Monitoring
      responses:
        '200':
          description: Successful retrieval of namespace statistics
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized access
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using Couchbase Server credentials.
  parameters:
    indexName:
      name: indexName
      in: path
      required: true
      description: The name of the Full Text Search index
      schema:
        type: string
  schemas:
    SearchIndexList:
      type: object
      description: List of all search index definitions
      properties:
        status:
          type: string
          description: Response status
        indexDefs:
          type: object
          description: Container for index definitions
          properties:
            uuid:
              type: string
              description: UUID of the index definitions set
            indexDefs:
              type: object
              description: Map of index name to index definition
              additionalProperties:
                $ref: '#/components/schemas/SearchIndexDefinition'
    SearchIndexResponse:
      type: object
      description: Single search index definition response
      properties:
        status:
          type: string
          description: Response status
        indexDef:
          $ref: '#/components/schemas/SearchIndexDefinition'
    SearchIndexDefinition:
      type: object
      description: Full Text Search index definition
      required:
        - name
        - type
        - sourceName
      properties:
        name:
          type: string
          description: Name of the search index
        type:
          type: string
          description: Type of the index
          enum:
            - fulltext-index
            - fulltext-alias
        sourceName:
          type: string
          description: Name of the source bucket
        sourceType:
          type: string
          description: Type of the data source
          default: couchbase
        sourceUUID:
          type: string
          description: UUID of the source bucket
        planParams:
          type: object
          description: Index partition and replication plan
          properties:
            maxPartitionsPerPIndex:
              type: integer
              description: Maximum partitions per index partition
            numReplicas:
              type: integer
              description: Number of index replicas
              minimum: 0
            indexPartitions:
              type: integer
              description: Number of index partitions
        params:
          type: object
          description: Index configuration parameters
          properties:
            mapping:
              type: object
              description: Type mapping configuration
              properties:
                default_mapping:
                  type: object
                  description: Default type mapping
                  properties:
                    enabled:
                      type: boolean
                      description: Whether the default mapping is enabled
                    dynamic:
                      type: boolean
                      description: Whether to dynamically index all fields
                types:
                  type: object
                  description: Named type mappings
                  additionalProperties:
                    type: object
                default_analyzer:
                  type: string
                  description: Default analyzer for the index
                default_type:
                  type: string
                  description: Default type for documents
            doc_config:
              type: object
              description: Document configuration
              properties:
                mode:
                  type: string
                  description: Document type identification mode
                  enum:
                    - scope.collection.type_field
                    - scope.collection.docid_prefix
                    - scope.collection.docid_regexp
                    - type_field
                    - docid_prefix
                    - docid_regexp
            store:
              type: object
              description: Store configuration
              properties:
                indexType:
                  type: string
                  description: Index storage type
                  enum:
                    - scorch
        uuid:
          type: string
          description: UUID of the index
    SearchQueryRequest:
      type: object
      description: Full-text search query request
      required:
        - query
      properties:
        query:
          type: object
          description: >-
            The search query object. Supports match, term, phrase, boolean,
            numeric_range, date_range, geo_distance, geo_bounding_box,
            conjunction, and disjunction query types.
          properties:
            match:
              type: string
              description: Text to match against the index
            field:
              type: string
              description: Specific field to search
            analyzer:
              type: string
              description: Analyzer to use for the query
            fuzziness:
              type: integer
              description: Fuzziness level for approximate matching
              minimum: 0
              maximum: 2
            prefix_length:
              type: integer
              description: Minimum prefix length for fuzzy matches
            boost:
              type: number
              description: Boost factor for relevance scoring
        size:
          type: integer
          description: Maximum number of results to return
          default: 10
        from:
          type: integer
          description: Offset for paginating results
          default: 0
        fields:
          type: array
          description: Fields to include in the response
          items:
            type: string
        highlight:
          type: object
          description: Highlight configuration for matched terms
          properties:
            style:
              type: string
              description: Highlight style
              enum:
                - html
                - ansi
            fields:
              type: array
              description: Fields to highlight
              items:
                type: string
        facets:
          type: object
          description: Facet definitions for aggregating results
          additionalProperties:
            type: object
            properties:
              field:
                type: string
                description: Field to facet on
              size:
                type: integer
                description: Maximum number of facet values
        sort:
          type: array
          description: Sort order for results
          items:
            oneOf:
              - type: string
              - type: object
        explain:
          type: boolean
          description: Whether to include scoring explanation
        ctl:
          type: object
          description: Query control parameters
          properties:
            timeout:
              type: integer
              description: Query timeout in milliseconds
            consistency:
              type: object
              description: Consistency requirements
              properties:
                level:
                  type: string
                  description: Consistency level
                  enum:
                    - at_plus
                    - not_bounded
    SearchQueryResult:
      type: object
      description: Full-text search query result
      properties:
        status:
          type: object
          description: Query execution status
          properties:
            total:
              type: integer
              description: Total number of search partitions queried
            failed:
              type: integer
              description: Number of partitions that failed
            successful:
              type: integer
              description: Number of partitions that succeeded
            errors:
              type: object
              description: Error messages from failed partitions
        total_hits:
          type: integer
          description: Total number of matching documents
        max_score:
          type: number
          description: Maximum relevance score
        took:
          type: integer
          description: Time taken in nanoseconds
        hits:
          type: array
          description: Array of matching documents
          items:
            type: object
            properties:
              index:
                type: string
                description: Index partition that matched
              id:
                type: string
                description: Document ID
              score:
                type: number
                description: Relevance score
              fields:
                type: object
                description: Requested field values
              fragments:
                type: object
                description: Highlighted fragments
                additionalProperties:
                  type: array
                  items:
                    type: string
              sort:
                type: array
                description: Sort values
                items: {}
        facets:
          type: object
          description: Faceted results
          additionalProperties:
            type: object
            properties:
              field:
                type: string
                description: Facet field name
              total:
                type: integer
                description: Total count
              missing:
                type: integer
                description: Count of documents without this field
              other:
                type: integer
                description: Count not represented in terms
              terms:
                type: array
                description: Facet term values
                items:
                  type: object
                  properties:
                    term:
                      type: string
                      description: Facet value
                    count:
                      type: integer
                      description: Number of documents with this value