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