Couchbase Search Indexes API

openapi: 3.1.0
info:
  title: Couchbase Analytics Service REST Allowed CIDRs Search Indexes API
  description: The Couchbase Analytics Service REST API provides access to the Analytics service for running complex analytical queries on operational data without impacting performance of key-value operations. It supports SQL++ queries for analytics, management of links to external data sources, and configuration of user-defined libraries. The service enables real-time analytics on JSON data alongside transactional workloads.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:8095
  description: Analytics Service (default port)
- url: https://localhost:18095
  description: Analytics 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:
    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'
    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
    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 Analytics Service REST API Documentation
  url: https://docs.couchbase.com/server/current/analytics/rest-analytics.html