The Couchbase Capella App Services Public API provides REST endpoints for mobile and edge application data synchronization with Couchbase Capella. It enables developers to manage document access, handle user authentication, and synchronize data between mobile devices and the cloud database.
openapi: 3.1.0
info:
title: Couchbase Capella App Services Public API
description: >-
The Couchbase Capella App Services Public API provides REST endpoints for
mobile and edge application data synchronization with Couchbase Capella.
It enables developers to manage document access, handle user
authentication, and synchronize data between mobile devices and the cloud
database. The API supports operations for reading and writing documents
through Sync Gateway, managing changes feeds, and handling replication
for offline-first mobile applications.
version: '3.0'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase Capella App Services Public API Documentation
url: https://docs.couchbase.com/cloud/app-services/references/rest_api_public.html
servers:
- url: https://{appEndpoint}
description: Capella App Services endpoint
variables:
appEndpoint:
default: example.apps.cloud.couchbase.com
description: The App Services endpoint URL
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.
security:
- basicAuth: []
- sessionAuth: []
paths:
/{db}:
get:
operationId: getDatabaseInfo
summary: Get database information
description: >-
Returns information about the specified database including its name,
update sequence, and instance start time.
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}/_all_docs:
get:
operationId: getAllDocs
summary: Get all documents
description: >-
Returns all documents in the database. By default, only the document
ID and revision are included. Use include_docs=true to include the
full document body.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/db'
- name: include_docs
in: query
required: false
description: Whether to include document bodies in the response
schema:
type: boolean
default: false
- name: channels
in: query
required: false
description: Filter results by channel name
schema:
type: string
- name: keys
in: query
required: false
description: Array of document IDs to retrieve
schema:
type: string
- name: startkey
in: query
required: false
description: Start key for the range to return
schema:
type: string
- name: endkey
in: query
required: false
description: End key for the range to return
schema:
type: string
- name: limit
in: query
required: false
description: Maximum number of results to return
schema:
type: integer
responses:
'200':
description: Successful retrieval of documents
content:
application/json:
schema:
$ref: '#/components/schemas/AllDocsResponse'
'401':
description: Unauthorized access
/{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 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: >-
Array of revision IDs or "all" to get all leaf revisions
schema:
type: string
- name: attachments
in: query
required: false
description: Whether to include attachment data
schema:
type: boolean
responses:
'200':
description: Successful retrieval of the document
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
description: Unauthorized access
'404':
description: Document not found
put:
operationId: putDocument
summary: Create or update a document
description: >-
Creates a new document or updates an existing document. For updates,
the current revision ID must be included 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 for updates
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The document body
responses:
'200':
description: Document created or updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentResponse'
'401':
description: Unauthorized access
'409':
description: Conflict due to revision mismatch
delete:
operationId: deleteDocument
summary: Delete a document
description: >-
Deletes a document by creating 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 of the document
schema:
type: string
responses:
'200':
description: Document deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentResponse'
'401':
description: Unauthorized access
'404':
description: Document not found
'409':
description: Conflict due to revision mismatch
/{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 for 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 to create or update
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/DocumentResponse'
'401':
description: Unauthorized access
/{db}/_bulk_get:
post:
operationId: bulkGet
summary: Get multiple documents
description: >-
Retrieves multiple documents by ID in a single request. This is
the primary endpoint used by Couchbase Lite for 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
description: Array of document identifiers
items:
type: object
required:
- id
properties:
id:
type: string
description: Document ID
rev:
type: string
description: Specific revision to retrieve
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 list of changes made to documents in the database in
sequence order. Supports long-polling, continuous, and one-shot
modes 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 to apply
schema:
type: string
enum:
- sync_gateway/bychannel
- name: channels
in: query
required: false
description: Comma-separated list of channel names 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 for continuous feed
schema:
type: integer
- name: timeout
in: query
required: false
description: Timeout in milliseconds for longpoll feed
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
post:
operationId: postChanges
summary: Get changes feed via POST
description: >-
Returns changes feed with parameters specified in the request body.
Identical to the GET endpoint but allows for complex filter parameters.
tags:
- Changes
parameters:
- $ref: '#/components/parameters/db'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
since:
type: string
description: Sequence number to start from
filter:
type: string
description: Filter function name
channels:
type: string
description: Channel names to filter by
include_docs:
type: boolean
description: Whether to include document bodies
limit:
type: integer
description: Maximum number of changes
feed:
type: string
enum:
- normal
- longpoll
- continuous
active_only:
type: boolean
description: Exclude deleted documents
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. Returns a session
cookie that can be used for subsequent requests.
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:
$ref: '#/components/schemas/SessionResponse'
'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
'401':
description: No active session
/{db}/_oidc:
get:
operationId: oidcAuthenticate
summary: Initiate OpenID Connect authentication
description: >-
Initiates the OpenID Connect authentication flow by redirecting
the user to the configured identity provider.
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/db'
- name: provider
in: query
required: false
description: Name of the OIDC provider
schema:
type: string
- name: offline
in: query
required: false
description: Whether to request a refresh token
schema:
type: boolean
responses:
'302':
description: Redirect to identity provider
'500':
description: OIDC not configured
/{db}/_oidc_callback:
get:
operationId: oidcCallback
summary: OpenID Connect callback
description: >-
Handles the callback from the identity provider after user
authentication and creates a Sync Gateway session.
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/db'
- name: code
in: query
required: true
description: Authorization code from the identity provider
schema:
type: string
- name: state
in: query
required: false
description: State parameter for CSRF protection
schema:
type: string
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
'401':
description: Authentication failed
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 authentication obtained from the _session endpoint.
parameters:
db:
name: db
in: path
required: true
description: The name of the database (keyspace)
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: Name of the database
update_seq:
type: integer
description: Current update sequence number
committed_update_seq:
type: integer
description: Committed update sequence number
instance_start_time:
type: integer
description: Instance start time in microseconds since epoch
compact_running:
type: boolean
description: Whether compaction is currently running
state:
type: string
description: Database state
enum:
- Online
- Offline
Document:
type: object
description: A Sync Gateway document
properties:
_id:
type: string
description: Document ID
_rev:
type: string
description: Current revision ID
_deleted:
type: boolean
description: Whether the document is deleted
_revisions:
type: object
description: Revision history
properties:
ids:
type: array
items:
type: string
start:
type: integer
_attachments:
type: object
description: Document attachments
additionalProperties:
type: object
properties:
content_type:
type: string
description: MIME type of the attachment
digest:
type: string
description: Content digest
length:
type: integer
description: Attachment size in bytes
revpos:
type: integer
description: Revision position
stub:
type: boolean
description: Whether this is a stub reference
additionalProperties: true
DocumentResponse:
type: object
description: Response after creating or updating a document
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 for _all_docs request
properties:
rows:
type: array
description: Array of document entries
items:
type: object
properties:
id:
type: string
description: Document ID
key:
type: string
description: Document key
value:
type: object
properties:
rev:
type: string
description: Current revision ID
doc:
type: object
description: Full document body (if include_docs=true)
total_rows:
type: integer
description: Total number of rows
update_seq:
type: integer
description: Current update sequence
ChangesResponse:
type: object
description: Changes feed response
properties:
results:
type: array
description: Array of changes
items:
type: object
properties:
seq:
description: Sequence number
id:
type: string
description: Document ID
changes:
type: array
description: List of revision changes
items:
type: object
properties:
rev:
type: string
description: Revision ID
deleted:
type: boolean
description: Whether the document was deleted
doc:
type: object
description: Document body (if include_docs=true)
last_seq:
description: Last sequence number in the response
pending:
type: integer
description: Number of pending changes
SessionResponse:
type: object
description: Session creation response
properties:
session_id:
type: string
description: Session identifier
expires:
type: string
format: date-time
description: Session expiration time
cookie_name:
type: string
description: Name of the session cookie