api.yaml

openapi: 3.1.0
security: []
servers:
  - url: 'http://{tenant}:8080'
    variables:
      tenant:
        default: localhost
        description: The running test server
info:
  title: Couchbase Lite Test Server API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: |-
    This is a REST API specification for Couchbase Lite Test Server.

    The APIs except GET [/](#operation/getInfo) requires the following request headers:
    * CBLTest-API-Version (integer)
    * CBLTest-Client-ID (UUID)

    The response headers of all APIs will contains the following response headers:
    * CBLTest-API-Version (integer)
    * CBLTest-Server-ID (UUID)

    Enum values:
    * Any enum values in the spec are case insensitive.

    KeyPath:
    * The [/updateDatabase](#operation/updateDatabase) and [/verifyDocuments](#operation/verifyDocuments) API are using the JSON's keypath to
      refer to a specific path in the document's properties tree.
    * The keypath structure can be described as follows:

      ```
      keypath  ::= ( [ DOLLAR DOT ] <property> | <index> ) <path>
      path     ::= (DOT <property> | <index>)* EOP
      index    ::= OBRACKET DIGIT+ CBRACKET
      property ::= ANY+
      EOP      ::= End of path
      DOT      ::= '.'
      DOLLAR   ::= '$'
      OBRACKET ::= '['
      CBRACKET ::= ']'
      DIGIT    ::=  '0' |'1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
      ANY      ::= (! (DOT | OBRACKET | CBRACKET | EOP) ) | ESCAPE
      ESCAPE   ::= '\' (! EOP )
      ```

    Changes
    2.0.2 (07/24/2025)
    * Add peer ID property to return value of [/startMultipeerReplicator](#operation/startMultipeerReplicator)

    2.0.1 (07/10/2025)
    * Add Merge-Dict Conflict Resolver

    2.0.0 (06/13/2025)
    * This is a breaking change: CBLTest-API-Version is now "2"
    * deprecate dataset_version
    * In ResetConfiguration, change the value for the "dataset" key to a url.
    * In UpdateDatabase and VerifyDocuments change the updatedBlobs keys to urls

    1.2.3 (12/09/2025)
    * Add transport type selection to [/startMultipeerReplicator](#operation/startMultipeerReplicator)

    1.2.2 (09/19/2025)
    * Add headers property to ReplicatorConfiguration

    1.2.1 (06/04/2025)
    * Add authenticator property to [/startMultipeerReplicator](#operation/startMultipeerReplicator)

    1.2.0 (04/09/2025)
    * Add [/startMultipeerReplicator](#operation/startMultipeerReplicator),
    * Add [/stopMultipeerReplicator](#operation/stopMultipeerReplicator) endpoint
    * Add [/getMultipeerReplicatorStatus](#operation/getMultipeerReplicatorStatus) endpoint

    1.1.1 (04/26/2025)
    * Modify newSession to accept dataset_version to set the version of the dataset to be downloaded

    1.1.0 (03/05/2025)
    * Add [/startListener](#operation/startListener) and [/stopListener](#operation/stopListener) endpoint

    1.0.0 (09/27/2024)
    * Replace setupLogging endpoint with expanded newSession endpoint
    * Add [/log](#operation/log) endpoint

    0.5.2 (09/25/2024)
    * Split getDocument into database and document key to more closely match other API

    0.5.1 (09/24/2024)
    * Added reset parameter "test"
    * Permit null as a collection list in reset
    * getDocument returns status 404 on doc not found.

    0.5.0 (09/17/2024)
    * Updated reset payload structure
    * Added stopReplicator
    * Added getDocument

    0.4.0 (08/29/2024)
    * Added runQuery endpoint

    0.3.1 (08/13/24)
    * Added conflictResolver to ReplicationCollectionEntry
    * Added special "empty" dataset to indicate a new empty database locally

    0.3.0 (08/10/24)
    * Added setupLogging endpoint

    0.2.4 (08/07/24)
    * Added pinnedServerCert to ReplicatorConfig

    0.2.3 (08/30/23)
    * Updated blob verification logic.
    * Added rules for determining blob's content_type.

    0.2.2 (08/25/23)
    * Added updatedBlobs option to /updateDatabase.
    * Added verification logic info including blob verification logic in /verifyDocuments.
    * Added blob file doesn't exist reason to /verifyDocuments description.
    * Added new /performMaintenance API

    0.2.1 (08/18/23)
    * Added note about out-of-scope functions to /verifyDocuments.
    * Changed wording in /snapshotDocuments description.

    0.2.0 (08/17/23)
    * Change verifyDocuments to verify all documents in snaphot

    0.1.9 (08/16/23)
    * Added ReplicatorConfiguration.enableAutoPurge
    * Added actual, expected, and document key to verifyDocuments's result

    0.1.8 (08/08/23)
    * Fixed missing ReplicationCollection.pullFilter
    * Added spec/replication-filter.md
    * Made DocumentReplication.flags required

    0.1.7 (08/04/23)
    * Fixed missing database in snapshotDocuments request
    * Added required keys to snapshotDocuments request
    * Add 'description' key to the verifyDocuments response

    0.1.6 (08/04/23)
    * Added JSON Path Spec to /updateDatabase

    0.1.5 (08/02/23)
    * Changed /updateDatabase to use keypaths for specifying the changes

    0.1.4 (07/28/23)
    * Fixed required fields and update description in ServerInfo.
    * Added additionalInfo to the ServerInfo.
    * Fixed required fields in ReplicationCollection.
    * Changed DocumentReplication.flags type from int to array of enums.
    * Added 'enableDocumentListener' to ReplicatorConfiguration.
    * Added a note that any enum values are case insensitive.
  version: 2.0.2
tags:
  - name: API
    description: The API endpoints of the test server
paths:
  /:
    get:
      operationId: getInfo
      tags:
        - API
      summary: Get Test Server information
      description: |-
        Get Test Server information containing the following information (tentative):

        * version : Test Server version number which is the same as CBL release number.
        * apiVersion: API version number. This will increase when we have breaking change.
        * cbl: The name of the CBL library used.
        * device : Device or platform information that the test server is running on.
        * additionalInfo: Any additional info regarding the server.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /reset:
    post:
      tags:
        - API
      summary: Reset the test server
      description: |-
        Reset the test server by deleting all of the databases and re-creating new databases as specified.
      operationId: reset
      requestBody:
        description: |-
          The request object describes how the databases will be setup after being reset. The request
          contains one optional key named "databases" which specifies the databases to be created.
          If not specified,  no databases will be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetConfiguration'
        required: true
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /getAllDocuments:
    post:
      tags:
        - API
      summary: Get all documents
      description: Get info including of document IDs and revision IDs all document from the specified collections
      operationId: getAllDocuments
      requestBody:
        description: |-
          The request object provides a list of the collections in the specified database. The properties include:

          * **database** : The database name
          * **collections** : An array of the collection names. The collection name is in the <scope-name>.<collection-name> format.

          If the specified database is not found, the 400 error will be returned.

          If the specified collections are not found, the response will not included the collections in its body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Collections'
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object where key is the collection name and the value is an array of objects containing document info including two keys, 'id' (documentID) and rev (revisionID).

            If the specified collections in the request, the dictionary will not contain those collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDocuments'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /getDocument:
    post:
      tags:
        - API
      summary: Get a document.
      description: |-
        Get a document by the document ID. The result is a dictionary containing
        document's properties and its metadata which are document ID and revision history.
      operationId: getDocument
      requestBody:
        description: |-
          The request object containing the collection name and document ID.
        content:
          application/json:
            schema:
              type: object
              required: ['database', 'document']
              properties:
                database:
                  type: string
                  example: 'db1'
                document:
                  $ref: '#/components/schemas/DocumentID'
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object containing document properties and metadata. The metadata
            keys are :
              * _id : Document ID
              * _revs: Revision history including the current revision ID as the first item.

            The format of the revision history is described in this document:
            https://github.com/couchbase/couchbase-lite-core/blob/master/modules/docs/pages/replication-protocol.adoc#4-revision-ids-and-histories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /updateDatabase:
    post:
      tags:
        - API
      summary: Update documents in the database.
      description: |-
        Perform document updates in batch. The request body contains an array of DatabaseUpdateItem object which describes
        how documents are updated, deleted or purged. For updating a document, the changes to the document are specified
        in 'updatedProperties' and 'removedProperties'.

        - **updatedProperties**:

          An array of objects. Each object contains one or more keys that are key paths into the document to be updated with the
          values associated with the keys. The objects in the array are evaluated in their natural order.

          The keypath identifies a unique location in the document's property tree starting from the root that follows
          dictionary properties and array elements. The keypath looks like "foo.bar[1].baz". The keypath structure can be found
          in the description at the beginning of this specification.

          The value at the location specified by the keypath is replaced with the value associated with the keypath, in the object
          regardless of its type. When a path in the keypath refers to a non-existent property, the key is added and
          its value set as a dictionary or an array depending on the type of the path.

           When a path in the keypath includes an array index that is out of bounds (the array is smaller than the specified index), the array
           is padded with nulls until it is exactly large enough to make the specified index legal.

           When a path (dictionary or array) in the keypath doesn't match the actual value type, the error will be returned.

           Examples :

          ```
             Document:
             {
               "name", {"first": "John", "last": "Doe"},
               "addresses": [{"city": "San Francisco"}, {"city": "Palo Alto"}]
             }

             Updates:

             name.last = "Tiger" -> {"name", {"first": "John", "last": "Tiger"}, ...}
             name.middle = "Sky" -> {"name", {"first": "John", "middle": "sky", "last": "Tiger"}, ...}
             name = "John Doe" -> {"name", "John Doe"}

             name.first.value = "John" ->  Error as the value of "first" is not the dictionary
             addresses[0].city = "Santa Clara" -> {"addresses": [{"city": "Santa Clara"}, {"city": "Palo Alto"}], ...}
             addresses[4].city = "San Mateo" -> {"addresses": [{"city": "Santa Clara"}, {"city": "Palo Alto"}, null, {"city": "San Mateo"}], ...}
             phones[1] = "650-123-4567" -> {"phones": [null, "650-123-4567"]}
          ```
        - **removedProperties**:

          An array of the key paths which refer to ditionary keys or array elements to be removed. If a keypath refer to a non-existent
          property or array element, the remove for the keypath will be no-ops. When removing multiple items in an array, the order of the array indexes
          should be from high to low to avoid index mutation during the removal.

        - **updatedBlobs**:

          A dictionary whose keys are the key paths into the document to be updated with the blob objects and values are
          the urls from which to retrieve the blobs to be put at the key path location.

          The logic to update blobs is similar to the logic when updating properties. The value at the location specified
          by the keypath is replaced with the blob object regardless of the value's type. When a path in the keypath
          refers to a non-existent property, the key is added and its value set as a dictionary or an array depending on
          the type of the path. When a path in the keypath includes an array index that is out of bounds, the array
          is padded with nulls until it is exactly large enough to make the specified index legal.

          The blob object is created from the content of the blob file to which the blob url refers: the value associated
          with the keypath in the request.  If the name of the file retrieved from the url ends with the extension ".zip"
          the file is unzipped, first, to recover the blob.   If the blob file name refers to non-existing blob file,
          a 400 request error will be returned.

          The content_type of the blob used when creating a blob object can be detected from the blob file name's extension
          (after it is unzipped, if necessary) according to the following rules:
            * "image/jpeg" for the .jpg
            * "application/octet-stream" for others

      operationId: updateDatabase
      requestBody:
        description: |-
          The request object containing document update items that will be performed in batch.
        content:
          application/json:
            schema:
              type: object
              required: ['database', 'updates']
              properties:
                database:
                  type: string
                  example: 'db1'
                updates:
                  type: array
                  items:
                    $ref: '#/components/schemas/DatabaseUpdateItem'
        required: true
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /startReplicator:
    post:
      tags:
        - API
      summary: Create and start a replicator
      description: |-
        Create and start a replicator. If success, the created replicator identifier will be returned.
      operationId: startReplicator
      requestBody:
        description: |-
          The request object containing the replicator configuration and the reset checkpoint flag
          used when starting the replicator.

          Note:
           - If no collections specified, the replicator will be created with the database which means
             the default collection will be used.
           - 400 Error returned when no collections set in the specified collection
        content:
          application/json:
            schema:
              type: object
              required: ['config']
              properties:
                config:
                  $ref: '#/components/schemas/ReplicatorConfiguration'
                reset:
                  type: boolean
                  example: false
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object containing the replicator object identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Replicator'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /stopReplicator:
    post:
      tags:
        - API
      summary: Stop a replicator
      description: |-
        Stop a replicator.
        Note:
          - Return 400 error when the specified replicator is not found.
          - The stopped replicator cannot be restarted.
      operationId: stopReplicator
      requestBody:
        description: |-
          The request object containing the replicator identifier.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Replicator'
        required: true
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /getReplicatorStatus:
    post:
      tags:
        - API
      summary: Get the current status of the replicator
      description: Get the current status of the replicator.
      operationId: getReplicatorStatus
      requestBody:
        description: |-
          The request object containing the replicator identifier.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Replicator'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplicatorStatus'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /snapshotDocuments:
    post:
      tags:
        - API
      summary: Snapshot documents for verifying changes
      description: |-
        Given a list of document IDs, snapshot the documents by getting and saving the documents in the memory.
        The non-existing or deleted documents will be recorded as null in the snapshot.

        The API will return a UUID of the snapshot, which can be used when calling POST /verifyDocuments to
        verify changes against the snapshot, for example, after finishing replication.
      operationId: snapshotDocuments
      requestBody:
        description: |-
          The request object containing the IDs of the documents to be snapshotted.
        content:
          application/json:
            schema:
              type: object
              required: ['database', 'documents']
              properties:
                database:
                  type: string
                  example: 'db1'
                documents:
                  type: array
                  items:
                    $ref: '#/components/schemas/DocumentID'
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object containing the snapshot identifier.
          content:
            application/json:
              schema:
                type: object
                required: ['id']
                properties:
                  id:
                    type: string
                    format: uuid
                    example: '123e0000-e89b-12d3-a456-426614174000'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /verifyDocuments:
    post:
      tags:
        - API
      summary: Verify document changes from a document snapshot.
      description: |-
        Verify all documents in the snapshot. The request body contains a list of changes to be verified.
        For the snapped-shot documents that are not in the list of changes, the documents will be
        verified as unchanged documents.

        Verification Logic:
        1. If the document specified in the delta doesn't exist in the snapshot, the 400 request error will be returned.
        2. If the document specified in the delta with change type PURGE or DELETE, the corresponding snapshot document
           value in the snaphot MUST be null.
        3. If the document specified in the delta with change type UPDATE, the expected document which is the
           corresponding snaphot document applied with the specified delta will be compared with the actual document
           which is the current document in the collection. The body of expected and actual document MUST be the same.
        4. When checking if the two blob objects (actual and expected) are equals, the platform blob's equals() method
           will be used. If the two blob objects are equals, in addition, the blob content of the two blobs will be
           compared. When reading the content of the actual blob, if the blob file is unexpectedly missing from
           the database, there could be a runtime exception thrown, please make sure to catch the exception and
           mark the verification result as failed with the appropriate description (See the case 6 in the response).
           For the actual / expected value of the blob, use the blob's properties.

           For that platform such as Swift that cannot catch the runtime exception to check that the blob is missing
           when getting the blob's content, use Database's getBlob(Dictionary blobProperties) which will throw
           CouchbaseLiteException when blob doesn't exist to get the same blob object for getting the blob content.

        Note:
        * The documents outside the snapshot will not be verified. To verify expected new documents
          can be done by including these new documents (not existing before) to the snapshot and verifying
          them with UPDATE changes.
        * Verifying unexpected new documents is out-of-scope. To do that use either POST /getAllDocuments or
          document replication listener to verify.
      operationId: verifyDocuments
      requestBody:
        description: Verify document changes from the given document snapshot recorded by using POST /snapshotDocuments.
        content:
          application/json:
            schema:
              type: object
              required: ['database', 'snapshot', 'changes']
              properties:
                database:
                  type: string
                  example: 'db1'
                snapshot:
                  type: string
                  format: uuid
                  example: '123e0000-e89b-12d3-a456-426614174000'
                changes:
                  type: array
                  items:
                    $ref: '#/components/schemas/DatabaseUpdateItem'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required: ['result']
                properties:
                  result:
                    type: boolean
                    example: false
                  description:
                    description: |-
                      Describing about the failed verification result. The information includes the document id,
                      and the reason that causes the verification to failed as follows:

                      Case 1 : Document should exists in the collection but it doesn't exist to verify.
                      Reason : Document '<doc-id>' in '<scope.collection>' was not found

                      Case 2 : Document should be deleted but it wasn't.
                      Reason : Document '<doc-id>' in '<scope.collection>' was not deleted

                      Case 3 : Document should be purged but it wasn't.
                      Reason : Document '<doc-id>' in '<scope.collection>' was not purged

                      Case 4 : Document has unexpected properties.
                      Reason : Document '<doc-id> in '<scope.collection>' had unexpected properties at key '<keypath>'

                      Case 5 : Document shouldn't exist (null value in the snapshot), but the document does exist.
                      Reason : Document '<doc-id> in '<scope.collection>' should not exist

                      Case 6 : Blob file doesn't exist in the database.
                      Reason : Document '<doc-id> in '<scope.collection>' had non-existing blob at key '<keypath>'

                      For the Case, The first unexpected keypath is shown in the reason description.
                      Its actual value, expected value, and the entire actual document body will be shown in
                      'actual', 'expected', 'document' key of the verification result object separately. If
                      the value of the 'actual' or 'expected' key is MISSING, the key will be omitted.

                      The following cases are listed as request errors (response status = 400):

                      Error Case 1 : The specified database in the request was not found.

                      Error Case 2 : The specified snapshot was not found.

                      Error Case 3 : The document in the collection to be verified didn't exist in the snapshot.

                    type: string
                    example: "Document 'doc-1' in 'scope.collection' has unexpected properties at key 'address.city'"
                  actual:
                    description: |-
                      The actual value of the unexpected keypath. If the actual keypath doesn't exist,
                      this 'actual' key will be omitted.
                    oneOf:
                      - type: boolean
                      - type: integer
                      - type: number
                      - type: string
                      - type: object
                      - type: array
                    example: "Santa Clara"
                  expected:
                    description: |-
                      The expected value of the unexpected keypath. If the expected keypath doesn't exist, this 'expected'
                      key will be omitted.
                    oneOf:
                      - type: boolean
                      - type: integer
                      - type: number
                      - type: string
                      - type: object
                      - type: array
                    example: "Santa Monica"
                  document:
                    description: |-
                      The actual document body of the document that has unexpected properties.
                    type: object
                    additionalProperties: {}
                    example: {'name': 'John Doe', 'address': {'city': 'Santa Clara', 'state': 'CA'}}
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /performMaintenance:
    post:
      tags:
        - API
      summary: Perform Database Maintenance
      description: Perform maintenance on the specified database per the specified maintenance type
      operationId: performMaintenance
      requestBody:
        description: |-
          The request object specifies the name of the database and the performance type be be performed on.
          If the database doesn't exist, 400 request error will be returned.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PerformMaintenanceConfiguration'
        required: true
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /newSession:
    post:
      tags:
        - API
      summary: Creates a new test session
      description: |-
        Creates a new session identified by a unique client ID. A session id (in the HTTP header CBLTest-Client-ID
        for all requests) must be introduced using this endpoint. A request with a client id not introduced here is in error.
        Optionally, this call allows instructing the test server to send all logging for the session
        (both from the server and from the CBL library) to a specified log slurper.
      operationId: newSession
      requestBody:
        description: |-
          The request object specifies a client id and, optionally the URL of a log slurper and the tag to be used when logging to it.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSession'
        required: true
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
  /runQuery:
    post:
      tags:
        - API
      summary: Runs a SQL++ query against a database
      description: Given a database and text query, executes the query and returns the result as JSON
      operationId: runQuery
      requestBody:
        description: |-
          The request object specifies the database and query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunQueryConfiguration'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResults'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /log:
    post:
      tags:
        - API
      summary: Log a message to the server log
      description: Given a message, immediately insert it into the server log stream
      operationId: log
      requestBody:
        description: |-
          The message to be logged
        content:
          application/json:
            schema:
              type: object
              required: ['message']
              properties:
                message::
                  type: string
                  example: 'Client has caught fire'
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /startListener:
    post:
      tags:
        - API
      summary: Starts a P2P listener
      description: |-
        Starts a P2P listener so that the device can act as the passive side of a P2P replication.
      operationId: startListener
      requestBody:
        description: |-
          The request object containing the collections to share and, optionally, the port to listen on and disableTLS flag.
        content:
          application/json:
            schema:
              type: object
              required: ['database', 'collections']
              properties:
                database:
                  type: string
                  example: 'db1'
                collections:
                  type: array
                  items:
                    type: string
                    example: 'store.cloths'
                port:
                  type: integer
                  example: 12345
                disableTLS:
                  type: boolean
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object containing the ID of the listener, and the port
            it is listening on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartListenerResponse'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /stopListener:
    post:
      tags:
        - API
      summary: Stops a P2P listener
      description: |-
        Stops a previously started P2P listener.
      operationId: stopListener
      requestBody:
        description: |-
          The request object containing the listener to stop.
        content:
          application/json:
            schema:
              type: object
              required: ['id']
              properties:
                id:
                  type: string
                  format: uuid
                  example: '123e4567-e89b-12d3-a456-426614174000'
        required: true
      responses:
        '200':
          description: |-
            Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /startMultipeerReplicator:
    post:
      tags:
        - API
      summary: Starts a Multipeer replicator
      description: |-
        Starts a multipeer replicator to create a mesh of connected clients.
      operationId: startMultipeerReplicator
      requestBody:
        description: |-
          The request object containing the collections to share and the peer group ID.  Optionally,
          it can contain an authenticator as well.  The default (null) behavior is accept all connections.
        content:
          application/json:
            schema:
              type: object
              required: ['peerGroupID', 'database', 'collections', 'identity']
              properties:
                peerGroupID:
                  type: string
                  example: 'com.couchbase.testing'
                database:
                  type: string
                  example: 'db1'
                collections:
                  type: array
                  items:
                    $ref: "#/components/schemas/ReplicationCollection"
                identity:
                  $ref: '#/components/schemas/MultipeerReplicatorIdentity'
                authenticator:
                  $ref: '#/components/schemas/MultipeerReplicatorCAAuthenticator'
                transports:
                  type: array
                  items:
                    type: string
                    uniqueItems: true
                    minItems: 1
                    enum: ['wifi', 'bluetooth']
                  example: ['wifi', 'bluetooth']
        required: true
      responses:
        '200':
          description: |-
            Success

            The response body is an object containing the ID of the listener, and the port
            it is listening on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipeerReplicator'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /stopMultipeerReplicator:
    post:
      tags:
        - API
      summary: Stops a Multipeer replicator
      description: |-
        Stops a previously started Multipeer Replicator.
      operationId: stopMultipeerReplicator
      requestBody:
        description: |-
          The request object containing the replicator to stop.
        content:
          application/json:
            schema:
              type: object
              required: ['id']
              properties:
                id:
                  type: string
                  format: uuid
                  example: '123e4567-e89b-12d3-a456-426614174000'
        required: true
      responses:
        '200':
          description: |-
            Success
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /getMultipeerReplicatorStatus:
    post:
      tags:
        - API
      summary: Gets the status of a multipeer replicator
      description: |-
        Gets the status of a multipeer replicator
      operationId: getMultipeerReplicatorStatus
      requestBody:
        description: |-
          The request object containing the replicator to query.
        content:
          application/json:
            schema:
              type: object
              required: ['id']
              properties:
                id:
                  type: string
                  format: uuid
                  example: '123e4567-e89b-12d3-a456-426614174000'
        required: true
      responses:
        '200':
          description: |-
            Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipeerReplicatorStatus'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Collections:
      type: object
      required: ['database', 'collections']
      properties:
        database:
          type: string
          example: 'db1'
        collections:
          type: array
          items:
            type: string
          example: ['catalog.cloths', 'catalog.shoes']
    CollectionDocuments:
      description: |-
        Each key is a fully qualified collection name.  The associated  value is a list of objects that must have an "id" key,
        and a "rev" key which is either a revtree id or a hlv cv
      type: object
      additionalProperties:
        type: string
      example: {
        'catalog.cloths': [{'id': 'c1', 'rev': '800@Bob'}, {'id': 'c2', 'rev': '1-9ef'}],
        'catalog.shoes': [{'id': 's1', 'rev': '1-ff0'}, {'id': 's2', 'rev': '1010@Alice'}]
      }
    Document:
      description: |-
        Contains document's properties and the metadata.
      type: object
      additionalProperties: {}
      example: {'_id': 'doc1', '_revs': '17f4ed7b51a50000@MlAW1NbbT8KcTRO8oPnpgw, 17f4ed7b42a70000@ScJAVJf3TdOUanAcByIcXg', 'foo': 'bar'}
    DocumentID:
      type: object
      required: ['collection', 'id']
      properties:
        collection:
          type: string
          example: 'store.cloths'
        id:
          type: string
          example: 'doc1'
    DocumentReplication:
      type: object
      required: ['collection', 'documentID', 'isPush', 'flags']
      properties:
        collection:
          type: string
          example: 'store.cloths'
        documentID:
          type: string
          example: 'doc1'
        isPush:
          type: boolean
          example: true
        flags:
          description: 'The document replication flags. An empty array indicates no flags.'
          type: array
          items:
            type: string
            enum: [deleted, accessRemoved]
            example: ['deleted']
        error:
          $ref: '#/components/schemas/Error'
    DatabaseUpdateItem:
      type: object
      required: ['type', 'collection', 'documentID']
      properties:
        type:
          type: string
          enum: ['UPDATE', 'DELETE', 'PURGE']
          example: 'UPDATE'
        collection:
          description: Collection full name
          type: string
          example: 'store.cloths'
        documentID:
          description: Document ID
          type: string
          example: 'doc1'
        updatedProperties:
          description: |-
            An array of dictionaries, each of which contains one or more keys that are key paths into the document
            to be updated with the values associated with the keys.
          type: array
          items:
            type: object
            additionalProperties: {}
            example:
              [
                {'people[47].address': {'street': 'Oak St. ', 'city': 'Auburn'}},
                {'people[3].address': {'street': 'Elm St. ', 'city': 'Sibley'}}
              ]
        removedProperties:
          description: An array of the key paths which refer to ditionary keys or array elements to be removed.
          type: array
          items:
            type: string
            example: ['people[22].address', 'people[3]']
        updatedBlobs:
          description: A dictionary whose keys are the key paths into the document to be updated with the
            blob objects and values are the urls from which to obtain the blob files.
          type: object
          additionalProperties: {}
          example: {'photo.thumbnail': 'https://media.githubusercontent.com/media/blob/s1.jpg'}
    Error:
      type: object
      required: ['domain', 'code']
      properties:
        domain:
          type: string
          enum: [TESTSERVER, CBL, POSIX, SQLITE, FLEECE]
          example: 'TESTSERVER'
        code:
          type: integer
          format: int32
          example: 1
        message:
          type: string
          example: 'This is an error'
    PerformMaintenanceConfiguration:
      type: object
      required: ['database', 'maintenanceType']
      properties:
        database:
          description: Database name
          type: string
          example: 'db1'
        maintenanceType:
          description: Maintenance type
          type: string
          enum: ['compact', 'integrityCheck', 'optimize', 'fullOptimize']
          example: 'compact'
    NewSession:
      type: object
      required: ['id']
      properties:
        id:
          description: The Session ID to appear in the header of all subsequent requests
          type: string
          example: 'c64aae38-87c1c-4524-823a-e267fc39c3c4'
        logging:
          type: object
          required: ['url', 'tag']
          properties:
            url:
              description: The URL of the LogSlurp server
              type: string
              example: 'localhost:8180'
            tag:
              description: The tag to identify this particular host
              type: string
              example: 'test-server[0]'
    Replicator:
      type: object
      required: ['id']
      properties:
        id:
          type: string
          format: uuid
          example: '123e4567-e89b-12d3-a456-426614174000'
    ReplicatorBasicAuthenticator:
      type: object
      required: ['type', 'username', 'password']
      properties:
        'type':
          type: string
          enum: ['BASIC']
        username:
          type: string
          example: 'user1'
        password:
          type: string
          example: 'p@ssw0rd'
    ReplicatorSessionAuthenticator:
      type: object
      required: ['type', 'sessionID']
      properties:
        'type':
          type: string
          enum: ['SESSION']
        sessionID:
          type: string
          example: 'SG12345'
        cookieName:
          type: string
          example: 'sessionID'
    ReplicatorConfiguration:
      type: object
      required: ['database', 'collections', 'endpoint']
      properties:
        database:
          type: string
          example: 'db1'
        collections:
          type: array
          items:
            $ref: '#/components/schemas/ReplicationCollection'
        endpoint:
          type: string
          example: "wss://localhost:4985/db"
        replicatorType:
          description: The default is pushAndPull.
          type: string
          enum:
            - pushAndPull
            - push
            - pull
          example: pushAndPull
        continuous:
          description: The default is false.
          type: boolean
          example: true
        authenticator:
          oneOf:
            - $ref: '#/components/schemas/ReplicatorBasicAuthenticator'
            - $ref: '#/components/schemas/ReplicatorSessionAuthenticator'
        enableDocumentListener:
          description: 'When enable the document listener, the ReplicatorStatus will include the documents containing a list of DocumentReplication. The default is false.'
          type: boolean
          example: false
        enableAutoPurge:
          description: The default is true.
          type: boolean
          example: false
        headers:
          description: HTTP headers to add to the request to the remote server.
          type: object
          additionalProperties:
            type: string
          example: {'header1': 'value1', 'header2': 'value2'}
        pinnedServerCert:
          description: The PEM representation of the TLS certificate that the remote is using
          type: string
          example: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
    ReplicationCollection:
      type: object
      required: ['names']
      properties:
        names:
          description: An array of collections that share the same configuration.
          type: array
          items:
            type: string
          example: ['store.cloths', 'store.shoes']
        channels:
          description: Channel names filter
          type: array
          items:
            type: string
          example: ['A', 'B']
        documentIDs:
          description: Document IDs filter
          type: array
          items:
            type: string
          example: ['doc1', 'doc2']
        pushFilter:
          description: Push Filter - A filter function called before push a document
          $ref: '#/components/schemas/ReplicationFilter'
        pullFilter:
          description: Pull Filter - A filter function called before saving a pulled document
          $ref: '#/components/schemas/ReplicationFilter'
        conflictResolver:
          description: One of the predefined conflict resolvers to use during replication
          $ref: '#/components/schemas/ConflictResolver'
    ReplicationFilter:
      description: |-
        Replication Function to call before pushing a document or before saving a pulled documents.
        The replication filter is predefined and implemented in the test server. Each filter will be given
        with a unique name that will be used to reference to the filter and will have a different parameters
        or none to pass to.

        See: spec/replication-filter.md for the list of predefined replication filters.
      type: object
      required: ['name']
      properties:
        name:
          type: string
          example: 'documentIDs'
        params:
          type: object
          additionalProperties: {}
          example: {'documentIDs': ['doc1', 'doc2']}
    ConflictResolver:
      description: |-
        The conflict resolver to set for this collection of the replication.  Each resolver is predefined
        and implemented in the test server.

        See: spec/conflict-resolvers.md for the list of predefined conflict resolvers
      type: object
      required: ['name']
      properties:
        name:
          type: string
          example: 'merge'
        params:
          type: object
          additionalProperties: {}
          example: {'property': 'region'}
    ReplicatorStatus:
      type: object
      required: ['activity', 'progress']
      properties:
        activity:
          type: string
          enum: ['STOPPED', 'OFFLINE', 'CONNECTING', 'IDLE', 'BUSY']
        progress:
          type: object
          required: ['completed']
          properties:
            completed:
              type: boolean
              example: true
        documents:
          description: |-
            'This will include only when enableDocumentListener is set to true in ReplicatorConfiguration when calling /startReplicator.
             The returned documents will be deleted after the documents are returned so the subsequnce call to get the replicator status
             will not contain the previous returned documents.'
          type: array
          items:
            $ref: '#/components/schemas/DocumentReplication'
        error:
          $ref: '#/components/schemas/Error'
    MultipeerReplicator:
      type: object
      required: ['id', "peerID"]
      properties:
        id:
          type: string
          format: uuid
          example: '123e4567-e89b-12d3-a456-426614174000'
        peerID:
          type: string
          format: base64
          example: 'scGCZGP6yPiMsbEn+kXk725S2RoSUeN662CJL+cQDpw='
    MultipeerReplicatorStatus:
      type: object
      required: ['replicators']
      properties:
        replicators:
          type: array
          items:
            type: object
            required: ['peerID', 'status', 'transport']
            properties:
              peerID:
                type: string
                example: '1234567890abcdef'
              status:
                $ref: '#/components/schemas/ReplicatorStatus'
              transport:
                type: string
                enum: ['WIFI', 'BLUETOOTH']
    MultipeerReplicatorIdentity:
      description: |-
        MultipeerReplicatorIdentity is used to specify a TLS certificate and key particular
        for a multipeer replciator so that it can identify itself.
      type: object
      required: ['encoding', 'data']
      properties:
        encoding:
          type: string
          enum: ['PKCS12']
          description: The type of data contained in the data field.
        data:
          type: string
          format: byte
          description: Base-64 encoded data of the format specified in encoding
        password:
          type: string
          example: 'pass'
          description: The password if the data is password protected
    MultipeerReplicatorCAAuthenticator:
      description: |-
        MultipeerReplicatorCAAuthenticator is used to authenticate the replicator using a CA certificate.
        The certificate is expected to be in PEM format, and any accepted client must have a certificate
        signed by the CA certificate.
      type: object
      required: ['type', 'certificate']
      properties:
        'type':
          type: string
          enum: ['CA-CERT']
        certificate:
          type: string
    ResetConfiguration:
      description: |-
        ResetConfiguration describes how the databases will be setup after the reset.
        It contains two optional keys. "test" specifies the neame of the test that will be run next.
        "databases" specifies the databases to be created. If it not specified, no databases are created.

        If specified "databases" if specified contains a dictionary describing how the database to be created
        as follows:
            * Null or an empty dictionary for creating an empty database.
            * A dictionary contains a single key named "collections", with a list of the collection names
              as its value, for creating a database with those collections.
            * A dictionary that contains the single key "dataset",
              whose value is the url for a dataset.  A dataset is a file named <dbname>.cblite2.zip
              which when unzipped is the prebuilt database named <dbname>.
      type: object
      properties:
        test:
          description: |-
            The name of the test that will be run next
          type: string
        databases:
          description: |-
            Contains database names as keys, with values are dictionaries descrbing how the databases
            will be created.
          type: ['null', object]
          additionalProperties:
            type: object
            oneOf:
              - properties:
                  collections:
                    description: |-
                      A list of fully qualified collection names (<scope>.<collection>) to be created in the database.
                      Collections may be null, but if an array is provided, it may not be empty.
                      The Collections parameter cannot be used together with dataset.'
                    type: ['null', array]
                    items:
                      type: string
                    example: ["_default.employees", "_default.departments"]
              - properties:
                  dataset:
                    description: 'Dataset url. Cannot be used together with collections.'
                    type: string
                    example: "https://media.githubusercontent.com/media/couchbaselabs/couchbase-lite-tests/refs/heads/main/dataset/4.0/travel.cblite2.zip"
          example: {
            'db1': {},
            'db2': {'collections': ["_default.employees"]},
            'db3': {'dataset': "https://media.githubusercontent.com/media/couchbaselabs/couchbase-lite-tests/refs/heads/main/dataset/4.0/travel.cblite2.zip"}}
    ServerInfo:
      type: object
      required: ['version', 'apiVersion', 'cbl', 'device']
      properties:
        version:
          description: 'Server version which is the same as CBL version.'
          type: string
          example: "3.1.0"
        apiVersion:
          description: 'API version number. This will increase when we have breaking changes.'
          type: integer
          example: 1
        cbl:
          description: 'The name of the CBL library used.'
          type: string
          example: "couchbase-lite-android"
        device:
          description: 'Device or platform information that the test server is running on.'
          type: object
          required: ['systemName', 'systemVersion']
          properties:
            model:
              description: 'Device Model Name'
              type: string
              example: 'Android Nexus X'
            systemName:
              description: 'Operating System Name'
              type: string
              example: 'Android OS Name'
            systemVersion:
              description: 'Operating System Version'
              type: string
              example: '6.0.0'
            systemApiVersion:
              description: 'Operating System API Version'
              type: string
              example: '19'
        additionalInfo:
          description: 'Any additional info regarding the server'
          type: string
          example: "CBL Commit 61671d0"
    RunQueryConfiguration:
      type: object
      required: ['database', 'query']
      properties:
        database:
          description: 'The database which will run the query provided'
          type: string
          example: 'db1'
        query:
          description: 'The SQL++ query to run'
          type: string
          example: "select meta().id from _default"
    QueryResults:
      type: object
      required: ['results']
      properties:
        results:
          description: 'The JSON serialized results of the query run'
          type: object
    StartListenerResponse:
      type: object
      required: ['id', 'port']
      properties:
        id:
          description: 'The ID of the listener'
          type: string
          format: uuid
          example: '123e4567-e89b-12d3-a456-426614174000'
        port:
          description: 'The port the listener is listening on'
          type: integer
          example: 12345
  responses:
    Error:
      description: |-
        HTTP Status:
          * 400 : Client request error (e.g. protocol error or JSON request body error) or CouchbaseLite error or exception.
          * 404 : Document not found.
          * 500 : Server error

        Response body: JSON object including domain, code, and message.
          * CouchbaseLite error: The domain (CBL,POSIX,SQLITE,FLEECE) and the code will be from CouchbaseLite error.
          * Non CouchbaseLite error:  The domain will be TESTSERVER and the code will be the same as the status code.

      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'