The Couchbase Sync Gateway Public REST API provides endpoints for mobile and edge clients to synchronize data with Couchbase Server through the Sync Gateway middleware. It supports document CRUD operations, changes feeds for real-time data synchronization, and user authentication.
openapi: 3.1.0
info:
title: Couchbase Sync Gateway Public REST API
description: >-
The Couchbase Sync Gateway Public REST API provides endpoints for mobile
and edge clients to synchronize data with Couchbase Server through the
Sync Gateway middleware. It supports document CRUD operations, changes
feeds for real-time data synchronization, and user authentication. The
API enables offline-first mobile applications to replicate data
bidirectionally between Couchbase Lite embedded databases and Couchbase
Server clusters.
version: '3.1'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase Sync Gateway Public REST API Documentation
url: https://docs.couchbase.com/sync-gateway/current/rest-api.html
servers:
- url: https://localhost:4984
description: Sync Gateway Public REST API (default port)
tags:
- name: Authentication
description: >-
Endpoints for user authentication and session management.
- name: Changes
description: >-
Endpoints for monitoring document changes and subscribing to change feeds.
- name: Database
description: >-
Endpoints for retrieving database information.
- name: Documents
description: >-
Endpoints for creating, reading, updating, and deleting documents.
- name: Local Documents
description: >-
Endpoints for managing local documents used by replication checkpoints.
- name: Server
description: >-
Endpoints for retrieving server-level information.
security:
- basicAuth: []
- sessionAuth: []
paths:
/:
get:
operationId: getServerInfo
summary: Get server information
description: >-
Returns information about the Sync Gateway server instance.
tags:
- Server
security: []
responses:
'200':
description: Successful retrieval of server information
content:
application/json:
schema:
type: object
properties:
couchdb:
type: string
description: CouchDB compatibility string
vendor:
type: object
properties:
name:
type: string
version:
type: string
version:
type: string
description: Sync Gateway version
/{db}:
get:
operationId: getDatabaseInfo
summary: Get database information
description: >-
Returns information about the specified database.
tags:
- Database
parameters:
- $ref: '#/components/parameters/db'
responses:
'200':
description: Successful retrieval of database information
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseInfo'
'401':
description: Unauthorized access
'404':
description: Database not found
/{db}/{docId}:
get:
operationId: getDocument
summary: Get a document
description: >-
Retrieves a document from the database by its document ID.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- $ref: '#/components/parameters/docId'
- name: rev
in: query
required: false
description: Specific revision ID to retrieve
schema:
type: string
- name: revs
in: query
required: false
description: Whether to include revision history
schema:
type: boolean
- name: open_revs
in: query
required: false
description: Retrieve all leaf revisions or specific revision IDs
schema:
type: string
- name: attachments
in: query
required: false
description: Whether to include inline attachment data
schema:
type: boolean
- name: show_exp
in: query
required: false
description: Whether to include document expiry information
schema:
type: boolean
responses:
'200':
description: Successful retrieval of the document
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
description: Unauthorized access
'403':
description: Forbidden - user does not have access
'404':
description: Document not found
put:
operationId: putDocument
summary: Create or update a document
description: >-
Creates a new document or updates an existing one. For updates, the
current revision must be specified either as a query parameter or
in the request body as _rev.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- $ref: '#/components/parameters/docId'
- name: rev
in: query
required: false
description: Current revision ID for update operations
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The document body
responses:
'200':
description: Document updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentWriteResponse'
'201':
description: Document created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentWriteResponse'
'401':
description: Unauthorized access
'403':
description: Forbidden - user does not have write access
'409':
description: Conflict due to revision mismatch
delete:
operationId: deleteDocument
summary: Delete a document
description: >-
Deletes a document by adding a tombstone revision. The current
revision must be specified.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- $ref: '#/components/parameters/docId'
- name: rev
in: query
required: true
description: Current revision ID of the document
schema:
type: string
responses:
'200':
description: Document deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentWriteResponse'
'401':
description: Unauthorized access
'404':
description: Document not found
'409':
description: Conflict due to revision mismatch
/{db}/_all_docs:
get:
operationId: getAllDocs
summary: Get all documents
description: >-
Returns all documents accessible to the authenticated user.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- name: include_docs
in: query
required: false
description: Whether to include document bodies
schema:
type: boolean
- name: channels
in: query
required: false
description: Filter by channel name
schema:
type: string
- name: startkey
in: query
required: false
description: Start key for range
schema:
type: string
- name: endkey
in: query
required: false
description: End key for range
schema:
type: string
- name: limit
in: query
required: false
description: Maximum number of results
schema:
type: integer
responses:
'200':
description: Successful retrieval of documents
content:
application/json:
schema:
$ref: '#/components/schemas/AllDocsResponse'
'401':
description: Unauthorized access
/{db}/_bulk_docs:
post:
operationId: bulkDocs
summary: Create or update multiple documents
description: >-
Creates or updates multiple documents in a single request. This is
the primary endpoint used by Couchbase Lite push replication.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- docs
properties:
docs:
type: array
description: Array of documents
items:
type: object
new_edits:
type: boolean
description: Whether to assign new revision IDs
default: true
responses:
'201':
description: Documents processed successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DocumentWriteResponse'
'401':
description: Unauthorized access
/{db}/_bulk_get:
post:
operationId: bulkGet
summary: Get multiple documents
description: >-
Retrieves multiple documents by their IDs in a single request. This
is the primary endpoint used by Couchbase Lite pull replication.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- name: attachments
in: query
required: false
description: Whether to include attachments
schema:
type: boolean
- name: revs
in: query
required: false
description: Whether to include revision history
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- docs
properties:
docs:
type: array
items:
type: object
required:
- id
properties:
id:
type: string
description: Document ID
rev:
type: string
description: Specific revision
responses:
'200':
description: Successful retrieval of documents
content:
application/json:
schema:
type: object
'401':
description: Unauthorized access
/{db}/_changes:
get:
operationId: getChanges
summary: Get changes feed
description: >-
Returns a sorted list of changes made to documents in the database.
Supports normal, longpoll, continuous, and websocket feed types
for real-time synchronization.
tags:
- Changes
parameters:
- $ref: '#/components/parameters/db'
- name: since
in: query
required: false
description: Sequence number to start from
schema:
type: string
- name: feed
in: query
required: false
description: Type of changes feed
schema:
type: string
enum:
- normal
- longpoll
- continuous
- websocket
- name: filter
in: query
required: false
description: Filter function
schema:
type: string
- name: channels
in: query
required: false
description: Comma-separated list of channels to filter by
schema:
type: string
- name: include_docs
in: query
required: false
description: Whether to include document bodies
schema:
type: boolean
- name: limit
in: query
required: false
description: Maximum number of changes to return
schema:
type: integer
- name: heartbeat
in: query
required: false
description: Heartbeat interval in milliseconds
schema:
type: integer
- name: timeout
in: query
required: false
description: Timeout for longpoll in milliseconds
schema:
type: integer
- name: style
in: query
required: false
description: Whether to return all leaf revisions
schema:
type: string
enum:
- main_only
- all_docs
- name: active_only
in: query
required: false
description: Whether to exclude deleted documents
schema:
type: boolean
responses:
'200':
description: Successful retrieval of changes
content:
application/json:
schema:
$ref: '#/components/schemas/ChangesResponse'
'401':
description: Unauthorized access
/{db}/_session:
post:
operationId: createSession
summary: Create a user session
description: >-
Authenticates a user and creates a new session cookie.
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/db'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- password
properties:
name:
type: string
description: Username
password:
type: string
description: User password
responses:
'200':
description: Session created successfully
content:
application/json:
schema:
type: object
properties:
session_id:
type: string
description: Session identifier
expires:
type: string
format: date-time
description: Session expiry time
cookie_name:
type: string
description: Session cookie name
'401':
description: Invalid credentials
delete:
operationId: deleteSession
summary: Delete current session
description: >-
Invalidates the current user session.
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/db'
responses:
'200':
description: Session deleted successfully
/{db}/_local/{localDocId}:
get:
operationId: getLocalDocument
summary: Get a local document
description: >-
Retrieves a local document. Local documents are not replicated and
are used internally for replication checkpoints.
tags:
- Local Documents
parameters:
- $ref: '#/components/parameters/db'
- name: localDocId
in: path
required: true
description: Local document ID
schema:
type: string
responses:
'200':
description: Successful retrieval of local document
content:
application/json:
schema:
type: object
'401':
description: Unauthorized access
'404':
description: Local document not found
put:
operationId: putLocalDocument
summary: Create or update a local document
description: >-
Creates or updates a local document. Local documents are not
replicated and are used for replication checkpoints.
tags:
- Local Documents
parameters:
- $ref: '#/components/parameters/db'
- name: localDocId
in: path
required: true
description: Local document ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Local document saved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentWriteResponse'
'401':
description: Unauthorized access
'409':
description: Conflict
delete:
operationId: deleteLocalDocument
summary: Delete a local document
description: >-
Deletes a local document.
tags:
- Local Documents
parameters:
- $ref: '#/components/parameters/db'
- name: localDocId
in: path
required: true
description: Local document ID
schema:
type: string
- name: rev
in: query
required: true
description: Current revision of the local document
schema:
type: string
responses:
'200':
description: Local document deleted successfully
'401':
description: Unauthorized access
'404':
description: Local document not found
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using Sync Gateway user credentials.
sessionAuth:
type: apiKey
in: cookie
name: SyncGatewaySession
description: >-
Session cookie from the _session endpoint.
parameters:
db:
name: db
in: path
required: true
description: The database name
schema:
type: string
docId:
name: docId
in: path
required: true
description: The document ID
schema:
type: string
schemas:
DatabaseInfo:
type: object
description: Database information
properties:
db_name:
type: string
description: Database name
update_seq:
type: integer
description: Current update sequence number
committed_update_seq:
type: integer
description: Committed update sequence
instance_start_time:
type: integer
description: Instance start time in microseconds
compact_running:
type: boolean
description: Whether compaction is running
state:
type: string
description: Database state
Document:
type: object
description: A Sync Gateway document
properties:
_id:
type: string
description: Document ID
_rev:
type: string
description: Revision ID
_deleted:
type: boolean
description: Whether the document is deleted
_exp:
type: string
description: Document expiry time
additionalProperties: true
DocumentWriteResponse:
type: object
description: Response from a document write operation
properties:
id:
type: string
description: Document ID
rev:
type: string
description: New revision ID
ok:
type: boolean
description: Whether the operation succeeded
AllDocsResponse:
type: object
description: Response from _all_docs
properties:
rows:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
value:
type: object
properties:
rev:
type: string
doc:
type: object
total_rows:
type: integer
update_seq:
type: integer
ChangesResponse:
type: object
description: Changes feed response
properties:
results:
type: array
items:
type: object
properties:
seq:
description: Sequence identifier
id:
type: string
description: Document ID
changes:
type: array
items:
type: object
properties:
rev:
type: string
deleted:
type: boolean
doc:
type: object
last_seq:
description: Last sequence in the response
pending:
type: integer
description: Number of pending changes