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.
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