Ditto Store API

openapi: 3.0.3
info:
  title: Ditto HTTP RPC API Keys Store 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.
security:
- api_key_or_jwt_token: []
tags:
- name: Store
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
      tags:
      - Store
  /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
      tags:
      - Store
  /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
      tags:
      - Store
  /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
      tags:
      - Store
  /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
      tags:
      - Store
components:
  schemas:
    Upsert:
      type: object
      description: Command to insert a new document or update an existing one if it already exists
      required:
      - collection
      - value
      properties:
        collection:
          type: string
          description: Name of the collection to upsert the document into
        id:
          $ref: '#/components/schemas/AnyValue'
          description: Optional ID for the document. If not provided, one will be generated
        value:
          $ref: '#/components/schemas/AnyValue'
          description: Document data to insert or update
        valueTypeOverrides:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TypeOverride'
          description: Optional type overrides for specific fields in the document
    UpdateCommandMethod:
      type: string
      description: Types of update operations that can be performed on document fields
      enum:
      - set
      - setAttachment
      - increment
      - replaceWithCounter
    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: Optional parameterized arguments to use in the query
        collection:
          type: string
          description: Name of the collection to remove documents from
        query:
          type: string
          description: Query expression that identifies which documents to remove
    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
    UpdateResult:
      type: object
      description: Result of executing an update operation
      required:
      - transactionId
      - updated
      - error
      properties:
        error:
          type: integer
          format: int64
          description: Number of documents that failed to update due to errors
        internalError:
          type: integer
          format: int64
          description: Number of documents that failed to update due to internal errors
        permissionDenied:
          type: integer
          format: int64
          description: Number of documents that couldn't be updated due to insufficient permissions
        transactionId:
          type: integer
          format: int64
          description: Transaction ID of the update operation
        updated:
          type: integer
          format: int64
          description: Number of documents successfully updated
    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'
    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
    WriteCommand:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/Update'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - update
      - allOf:
        - $ref: '#/components/schemas/Upsert'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - upsert
      - allOf:
        - $ref: '#/components/schemas/Remove'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - remove
      description: A write operation to perform in a transaction. Can be an update, upsert, or remove command.
      discriminator:
        propertyName: method
        mapping:
          remove: '#/components/schemas/Remove'
          update: '#/components/schemas/Update'
          upsert: '#/components/schemas/Upsert'
    AnyValue: {}
    Update:
      type: object
      description: Command to update existing documents in a collection that match a query
      required:
      - collection
      - query
      - commands
      properties:
        args:
          $ref: '#/components/schemas/AnyValue'
          description: Optional parameterized arguments to use in the query
        collection:
          type: string
          description: Name of the collection containing documents to update
        commands:
          type: array
          items:
            $ref: '#/components/schemas/UpdateCommand'
          description: Array of update operations to apply to matching documents
        query:
          type: string
          description: Query expression that identifies which documents to update
    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
    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'
    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
    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
    UpdateCommand:
      type: object
      description: Specifies how to modify a field in matching documents
      required:
      - method
      - path
      - value
      properties:
        method:
          $ref: '#/components/schemas/UpdateCommandMethod'
          description: Type of update operation to perform
        path:
          type: string
          description: Path to the field to update within the document
        value:
          $ref: '#/components/schemas/AnyValue'
          description: New value to set for the field
    Sort:
      type: object
      description: Specifies how to sort query results by a property
      required:
      - property
      - direction
      properties:
        direction:
          $ref: '#/components/schemas/Direction'
          description: Sort direction (ascending or descending)
        property:
          type: string
          description: Document property to sort by
    TypeOverride:
      type: string
      description: Specifies special data types for fields when upserting documents
      enum:
      - counter
      - register
      - attachment
    RemoveResult:
      type: object
      description: Result of executing a remove operation
      required:
      - transactionId
      - deleted
      properties:
        deleted:
          type: integer
          format: int64
          description: Number of documents successfully deleted
        internalError:
          type: integer
          format: int64
          description: Number of documents that failed to delete due to internal errors
        permissionDenied:
          type: integer
          format: int64
          description: Number of documents that couldn't be deleted due to insufficient permissions
        transactionId:
          type: integer
          format: int64
          description: Transaction ID of the remove operation
    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'
    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
    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
    WriteCommandResult:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/UpdateResult'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - update
      - allOf:
        - $ref: '#/components/schemas/UpsertResult'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - upsert
      - allOf:
        - $ref: '#/components/schemas/RemoveResult'
        - type: object
          required:
          - method
          properties:
            method:
              type: string
              enum:
              - remove
      description: Result of executing a write command. Contains the specific result type based on the command method.
      discriminator:
        propertyName: method
        mapping:
          remove: '#/components/schemas/RemoveResult'
          update: '#/components/schemas/UpdateResult'
          upsert: '#/components/schemas/UpsertResult'
    WriteRequest:
      type: object
      description: Request to execute one or more 

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