Couchbase Search Indexes API

openapi: 3.2.0
info:
  title: Couchbase Search Service REST Search Indexes 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
servers:
- url: https://localhost:8094
  description: Search Service (default port)
- url: https://localhost:18094
  description: Search Service (SSL)
security:
- basicAuth: []
tags:
- name: Search Indexes
  description: Endpoints for creating, retrieving, updating, and deleting Full Text Search index definitions.
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}/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
components:
  schemas:
    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
    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'
  parameters:
    indexName:
      name: indexName
      in: path
      required: true
      description: The name of the Full Text Search index
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Couchbase Server credentials.
externalDocs:
  description: Couchbase Search Service REST API Documentation
  url: https://docs.couchbase.com/server/current/rest-api/rest-fts.html