Ditto Cloud HTTP API

openapi: 3.0.3
info:
  title: Ditto HTTP RPC API
  version: 4.0.0
  description: The Ditto HTTP RPC API provides a RESTful interface for interacting
    with Ditto's distributed data store. It enables you to query, insert, update and
    delete data across your Ditto network while maintaining strong consistency guarantees.
servers:
- url: '{base_url}/api/v4'
  description: The Ditto Big Peer acts as a central synchronization point and data
    store in your Ditto network. It coordinates data replication between peers and
    provides a consistent view of your data.
  variables:
    base_url:
      default: https://YOUR_CLOUD_URL_ENDPOINT
      description: Your Cloud URL Endpoint from the Ditto Portal (Connect via HTTP),
        prefixed with https:// to form the base URL.
paths:
  /store/count:
    post:
      description: Count the number of documents in a collection that match a specified
        query. This endpoint is useful for pagination, analytics, and understanding
        the size of your dataset.
      operationId: count_endpoint
      parameters:
      - name: X-DITTO-TXN-ID
        in: header
        description: Optional transaction ID header that ensures consistency. If specified,
          the operation will only proceed if the Big Peer's transaction ID is equal
          to or greater than this value. This prevents reading stale data by ensuring
          you're operating on a sufficiently up-to-date version of the database.
        required: false
        deprecated: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountRequest'
        required: true
      responses:
        '200':
          description: The count operation completed successfully. Returns the total
            number of matching documents and the transaction ID of the operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
            application/cbor:
              schema:
                $ref: '#/components/schemas/CountResponse'
        '400':
          description: The request was malformed. This typically indicates an invalid
            query syntax, unknown collection, or invalid parameters. Check the error
            message for specific details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '401':
          description: Authentication failed. Ensure you're providing a valid API
            key or JWT token in the Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '500':
          description: An unexpected error occurred on the server. This could indicate
            a temporary service disruption or internal error. Retry the request after
            a brief delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
      deprecated: false
  /store/execute:
    post:
      description: Execute a Ditto Query Language (DQL) statement against your data
        store. DQL is a powerful query language that supports complex queries, updates,
        and data manipulation. This endpoint serves as the primary interface for running
        DQL operations. See the comprehensive DQL guide for detailed syntax and examples.
      summary: Execute a DQL query
      operationId: execute_endpoint
      parameters:
      - name: X-DITTO-TXN-ID
        in: header
        description: Optional transaction ID that ensures consistency across operations.
          When provided, the operation will only execute if the Big Peer's current
          transaction ID meets or exceeds this value, preventing stale reads and ensuring
          causal consistency in your application.
        required: false
        deprecated: false
        schema:
          type: integer
          format: int64
      requestBody:
        description: The DQL statement to execute, along with any parameterized arguments.
          Using parameterized queries with the args field helps prevent injection
          attacks and improves query performance through statement caching.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: The DQL statement executed successfully. The response includes
            the results of the query, any mutated document IDs, the transaction ID,
            and any warnings that occurred during execution. For SELECT queries, results
            appear in the items array. For mutations, affected IDs appear in mutatedDocumentIds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                transactionId: 100
                queryType: select
                items:
                - _id: 1
                  name: Francis
                  favoriteBook:
                    title: The Great Gatsby
                    published: 1925
                mutatedDocumentIds: []
                error: {}
                warnings: []
                totalWarningsCount: 0
        '400':
          description: The DQL statement was invalid or malformed. This could be due
            to syntax errors, invalid collection names, type mismatches, or other
            query validation failures. Check the error response for detailed information
            about what went wrong.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
        '401':
          description: Authentication failed. Ensure you're providing a valid API
            key or JWT token in the Authorization header and that it has sufficient
            permissions for the requested operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
        '404':
          description: The requested transaction ID (if specified) is not available
            on the Big Peer. This typically means the Big Peer has not yet reached
            that transaction ID or the transaction has been garbage collected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
        '408':
          description: The query execution timed out. This can happen with complex
            queries over large datasets or when the system is under heavy load. Consider
            optimizing your query or adding appropriate indexes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
        '500':
          description: An unexpected server error occurred while executing the query.
            This could be due to resource constraints, internal errors, or temporary
            service disruptions. The operation may succeed if retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
        '503':
          description: The service is temporarily unavailable, typically due to maintenance
            or capacity issues. Clients should implement exponential backoff and retry
            the request later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                queryType: unknown
                items: []
                mutatedDocumentIds: []
                error:
                  description: '...'
                warnings: []
                totalWarningsCount: 0
      deprecated: false
  /store/find:
    post:
      description: Query documents in a collection using a flexible query language.
        This endpoint supports pagination, sorting, and complex queries to help you
        efficiently retrieve exactly the data you need.
      operationId: find_endpoint
      parameters:
      - name: X-DITTO-TXN-ID
        in: header
        description: Optional transaction ID that ensures read consistency. The operation
          will only proceed if the Big Peer's transaction ID is at least this value,
          preventing reads of stale data.
        required: false
        deprecated: false
        schema:
          type: integer
          format: int64
      requestBody:
        description: Specify the collection to query, the query conditions, and optional
          parameters like limit, offset, and sort order. The query can be parameterized
          using the args field for safe and efficient execution.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindRequest'
        required: true
      responses:
        '200':
          description: The query executed successfully. Returns an array of matching
            documents and the transaction ID of the read operation. If no documents
            match, the documents array will be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindResponse'
            application/cbor:
              schema:
                $ref: '#/components/schemas/FindResponse'
        '400':
          description: The request was invalid. This could be due to malformed query
            syntax, invalid collection name, or invalid parameter values. Check the
            error message for details on how to correct the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '401':
          description: Authentication failed. Verify that you're providing a valid
            API key or JWT token and that it has appropriate read permissions for
            the requested collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '500':
          description: An unexpected server error occurred. This could be due to resource
            constraints or internal errors. The request may succeed if retried after
            a brief delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
      deprecated: false
  /store/findbyid:
    post:
      description: Retrieve a single document by its unique identifier. This is the
        most efficient way to fetch a specific document when you know its ID.
      operationId: find_by_id_endpoint
      parameters:
      - name: X-DITTO-TXN-ID
        in: header
        description: Optional transaction ID for ensuring read consistency. The operation
          will only proceed if the Big Peer's transaction ID is at least this value,
          preventing reads of stale data.
        required: false
        deprecated: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindByIdRequest'
        required: true
      responses:
        '200':
          description: The document was found and retrieved successfully. Returns
            the document data along with the transaction ID of the read operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindByIdResponse'
            application/cbor:
              schema:
                $ref: '#/components/schemas/FindByIdResponse'
        '400':
          description: The request was invalid. This could be due to an invalid ID
            format, unknown collection, or other parameter validation failures. Check
            the error message for specific details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '401':
          description: Authentication failed. Ensure you're providing a valid API
            key or JWT token with appropriate read permissions for the requested collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '500':
          description: An unexpected server error occurred. This could be due to resource
            constraints or internal errors. The request may succeed if retried after
            a brief delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
      deprecated: false
  /store/write:
    post:
      description: Perform one or more write operations (updates, upserts, or removals)
        in a single atomic transaction. This endpoint ensures all operations either
        succeed or fail together, maintaining data consistency.
      operationId: write_endpoint
      parameters:
      - name: X-DITTO-TXN-ID
        in: header
        description: Optional transaction ID that ensures write consistency. The operation
          will only proceed if the Big Peer's transaction ID is at least this value,
          preventing concurrent modification issues.
        required: false
        deprecated: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteRequest'
        required: true
      responses:
        '200':
          description: The write operations completed successfully. Returns results
            for each command, including the new transaction ID and counts of affected
            documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
            application/cbor:
              schema:
                $ref: '#/components/schemas/WriteResponse'
        '400':
          description: The request was invalid. This could be due to malformed commands,
            invalid collection names, or data validation failures. Check the error
            message for details on the specific issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '401':
          description: Authentication failed. Verify that you're providing a valid
            API key or JWT token with appropriate write permissions for the affected
            collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '403':
          description: The authenticated user lacks permission to perform one or more
            of the requested write operations. Check your access control settings
            and ensure proper authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '500':
          description: An unexpected server error occurred during the write operation.
            The transaction was rolled back to maintain consistency. Retry the request
            after a brief delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
      deprecated: false
  /sync/remote_execute:
    post:
      description: Execute a DQL statement on specific connected peers in your Ditto
        network. This powerful feature allows you to query and manipulate data directly
        on edge devices that match your specified criteria.
      operationId: remote_execute_endpoint
      requestBody:
        description: Specify both the peer selection criteria (using SYNC CONTEXT)
          and the DQL statement to execute on matching peers. This enables targeted
          operations on specific devices or groups of devices in your network.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoteExecuteRequest'
        required: true
      responses:
        '200':
          description: The remote execution request was processed successfully. Returns
            results from each matching peer, including any data retrieved, errors
            encountered, and execution statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoteExecuteResponse'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RemoteExecuteResponse'
        '400':
          description: The request was invalid. This could be due to incorrect SYNC
            CONTEXT syntax, invalid DQL statement, or other parameter validation failures.
            Check the error message for specific details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '401':
          description: Authentication failed. Ensure you're providing a valid API
            key or JWT token with appropriate permissions for remote execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
        '500':
          description: An unexpected server error occurred while processing the remote
            execution request. This could be due to network issues, peer connectivity
            problems, or internal errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RpcError'
            application/cbor:
              schema:
                $ref: '#/components/schemas/RpcError'
      deprecated: false
components:
  schemas:
    CountRequest:
      type: object
      description: Request parameters for counting documents in a collection. Use
        this to get the total number of documents matching specific criteria.
      required:
      - collection
      - query
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Optional parameters to use in the parameterized query, providing
            safe value substitution
        collection:
          type: string
          description: The name of the collection to count documents in
        query:
          type: string
          description: A query expression that filters which documents to count. Use
            parameterized values with :param syntax for better security and performance
      example:
        collection: people
        query: favoriteBook.title == 'The Great Gatsby'
    CountResponse:
      type: object
      description: Response from a count operation, providing both the count and transaction
        ID for consistency tracking.
      required:
      - count
      - txnId
      properties:
        count:
          type: integer
          format: int64
          description: The total number of documents that matched the query criteria
        txnId:
          type: integer
          format: int64
          description: The transaction ID at which this count was performed, useful
            for consistency checks
      example:
        count: 100
        txnId: 9000
    Direction:
      type: string
      description: Sort direction for query results. Use 'asc' for ascending order
        (A to Z, 1 to 9) or 'desc' for descending order (Z to A, 9 to 1).
      enum:
      - asc
      - desc
    Document:
      type: object
      description: Represents a document in the Ditto store. Documents are schema-free
        and can contain nested fields of various CRDT types for conflict-free replication.
      required:
      - id
      - fields
      properties:
        fields:
          $ref: '#/components/schemas/AnyValue'
          description: The document's content, which can include any valid JSON data
            types and special Ditto CRDT types
        id:
          $ref: '#/components/schemas/AnyValue'
          description: The unique identifier for this document within its collection
    FindByIdRequest:
      type: object
      description: Request parameters for retrieving a specific document by its ID.
        This is the most efficient way to fetch a single document when you know its
        identifier.
      required:
      - collection
      - id
      properties:
        collection:
          type: string
          description: The name of the collection containing the document
        formatAttachment:
          type: boolean
          default: false
          description: When true, any attachment fields will be formatted for easier
            consumption
        id:
          $ref: '#/components/schemas/AnyValue'
          description: The unique identifier of the document to retrieve
        serializedAs:
          $ref: '#/components/schemas/SerializedAs'
          description: Controls how the document data is serialized in the response
      example:
        collection: people
        id: abc123
    FindByIdResponse:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          txnId:
            type: integer
            format: int64
            description: The transaction ID at which this document was retrieved,
              useful for consistency tracking
    FindRequest:
      type: object
      description: Request parameters for querying documents in a collection. Supports
        filtering, pagination, and sorting to help you retrieve exactly the data you
        need.
      required:
      - collection
      - query
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Named parameters to use in the query, providing safe value
            substitution and better query performance
        collection:
          type: string
          description: The name of the collection to query
        describe:
          type: boolean
          default: false
          description: When true, includes additional metadata about the query execution
        formatAttachment:
          type: boolean
          default: false
          description: When true, formats any attachment fields for easier consumption
        limit:
          type: integer
          format: int32
          description: Maximum number of documents to return. Use with offset for
            pagination.
          default: 1000
        offset:
          type: integer
          format: int32
          description: Number of documents to skip before starting to return results.
            Use with limit for pagination.
        query:
          type: string
          description: The query expression that filters which documents to return.
            Use parameterized values with :param syntax for better security and performance.
        serializedAs:
          $ref: '#/components/schemas/SerializedAs'
          description: Controls how the document data is serialized in the response
        sort:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
          description: Specifies the order in which to return matching documents
      example:
        collection: people
        query: favoriteBook.title == 'The Great Gatsby'
    FindResponse:
      type: object
      required:
      - documents
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
          description: Array of documents matching the query criteria
        txnId:
          type: integer
          format: int64
          description: The transaction ID at which this query was performed
      example:
        documents:
          id: 1
          contents:
            name: Francis
            favoriteBook:
              title: The Great Gatsby
              published: 1925
        txnId: 9000
    QueryRequest:
      type: object
      description: Request parameters for executing a DQL statement. DQL is Ditto's
        powerful query language that supports complex queries and data modifications.
      required:
      - statement
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Named parameters to use in the DQL statement, providing safe
            value substitution and better query performance
        statement:
          type: string
          description: The DQL statement to execute. See https://docs.ditto.live/dql-guide
            for comprehensive documentation on DQL syntax and features.
      example:
        statement: SELECT * FROM people WHERE favoriteBook.title = :title
        args:
          title: The Great Gatsby
    QueryResponse:
      type: object
      description: Response from executing a DQL statement. Contains query results,
        affected document IDs, and any warnings or errors that occurred.
      required:
      - queryType
      - items
      - mutatedDocumentIds
      - warnings
      - totalWarningsCount
      properties:
        error:
          $ref: '#/components/schemas/QueryResponseError'
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnyValue'
        mutatedDocumentIds:
          type: array
          items:
            $ref: '#/components/schemas/AnyValue'
        queryType:
          type: string
          description: Indicates the type of query that was executed
        totalWarningsCount:
          type: integer
          format: int64
          description: Total number of warnings generated during query execution
        transactionId:
          type: integer
          format: int64
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/QueryResponseWarning'
    QueryResponseError:
      type: object
      description: An error occurred that prevented the query from executing or completing
        successfully
      properties:
        description:
          type: string
    QueryResponseWarning:
      type: object
      description: Indicates any run-time warnings that might arise during query execution
      required:
      - description
      properties:
        _id:
          $ref: '#/components/schemas/AnyValue'
        description:
          type: string
    RemoteExecuteError:
      type: object
      required:
      - description
      properties:
        description:
          type: string
    RemoteExecutePeerItem:
      type: object
      description: Represents the response data returned from executing a query on
        a specific peer in the network. Contains query results, timing information,
        and any errors or warnings that occurred.
      properties:
        elapsedMilliseconds:
          $ref: '#/components/schemas/AnyValue'
          description: The time taken to execute the query on this peer in milliseconds
        error:
          $ref: '#/components/schemas/RemoteExecuteError'
          description: Any error that occurred while executing the query on this peer
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnyValue'
          description: The array of results returned from executing the query on this
            peer
        peer:
          $ref: '#/components/schemas/AnyValue'
          description: Information identifying the specific peer that executed the
            query
        totalWarningsCount:
          $ref: '#/components/schemas/AnyValue'
          description: Total number of warnings generated during query execution on
            this peer
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/AnyValue'
          description: Array of warnings generated during query execution on this
            peer
    RemoteExecuteRequest:
      type: object
      description: Request object for executing a DQL query remotely on specific peers
        in the network. The query must include a SYNC CONTEXT clause to specify target
        peers.
      required:
      - statement
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Optional parameterized arguments to use in the query statement
        statement:
          type: string
          description: A DQL statement that must include a SYNC CONTEXT clause to
            specify target peers. See https://docs.ditto.live/dql-guide for syntax
            details.
      example:
        statement: SYNC CONTEXT ( PEERS WHERE peerKeyString = 'pkAg' ) SELECT * FROM
          cars WHERE _id = '1'
    RemoteExecuteResponse:
      type: object
      description: Response from executing a remote query across specified peers.
        Contains results and any errors that occurred.
      required:
      - result
      properties:
        error:
          $ref: '#/components/schemas/RemoteExecuteError'
          description: Any error that prevented the remote query from executing successfully
        result:
          type: array
          items:
            $ref: '#/components/schemas/RemoteExecutePeerItem'
          description: Array of results from each peer that executed the query
    Remove:
      type: object
      description: Command to remove documents or fields from a collection that match
        the specified query
      required:
      - collection
      - query
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Option

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ditto-live/refs/heads/main/openapi/ditto-live-cloud-http-api-openapi.yml