> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Write docs with Legacy QL

> 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.

<Warning>
  This is a legacy endpoint that uses the [Legacy Query Language](/dql/query-syntax-legacy).

  To use [DQL](/dql), the current Ditto query language, consider using the [execute](./post-storeexecute) endpoint.
</Warning>


## OpenAPI

````yaml post /store/write
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://REPLACE_WITH_MY_APP_ID.cloud.ditto.live
        description: >-
          Your unique Ditto application endpoint URL, found in the Ditto Portal
          under Application Settings. Replace REPLACE_WITH_MY_APP_ID with your
          actual app ID.
security:
  - api_key_or_jwt_token: []
externalDocs:
  url: https://docs.ditto.live/http/installation/
  description: >-
    For more detailed instructions on how to use this API and the Ditto SDK,
    please see the documentation.
paths:
  /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
components:
  schemas:
    WriteRequest:
      type: object
      description: Request to execute one or more write commands in a transaction
      required:
        - commands
      properties:
        commands:
          type: array
          items:
            $ref: '#/components/schemas/WriteCommand'
          description: Array of write commands to execute in the transaction
      example:
        commands:
          - method: upsert
            collection: people
            id: 1
            value:
              name: Susan
              age: 31
              favoriteBook:
                published: 1925
                title: The Great Gatsby
    WriteResponse:
      type: object
      description: Response containing results of executing a write transaction
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/WriteCommandResult'
          description: Array of results for each write command executed in the transaction
    RpcError:
      type: object
      description: Error response returned when an API request fails
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable description of what went wrong
      example:
        message: Some kind of human readable description of the error
    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:
            $ref: '#/components/schemas/Remove'
          update:
            $ref: '#/components/schemas/Update'
          upsert:
            $ref: '#/components/schemas/Upsert'
    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:
            $ref: '#/components/schemas/RemoveResult'
          update:
            $ref: '#/components/schemas/UpdateResult'
          upsert:
            $ref: '#/components/schemas/UpsertResult'
    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
    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
    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
    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
    UpsertResult:
      type: object
      description: Result of executing an upsert operation
      required:
        - transactionId
      properties:
        transactionId:
          type: integer
          format: int64
          description: Transaction ID of the upsert operation
    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
    AnyValue: {}
    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
    TypeOverride:
      type: string
      description: Specifies special data types for fields when upserting documents
      enum:
        - counter
        - register
        - attachment
    UpdateCommandMethod:
      type: string
      description: Types of update operations that can be performed on document fields
      enum:
        - set
        - setAttachment
        - increment
        - replaceWithCounter
  securitySchemes:
    api_key_or_jwt_token:
      type: http
      scheme: bearer
      bearerFormat: API Key or JWT
      description: >-
        Authentication using either an API key or JWT token in the Authorization
        header

````