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