---
title: "POST /store/write"
method: POST
path: "/store/write"
---

# POST /store/write

`POST /store/write`

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.

## Headers

- `X-DITTO-TXN-ID` integer

## Request body

- WriteRequest — Request to execute one or more write commands in a transaction
  - `commands` WriteCommand[], required — Array of write commands to execute in the transaction
    - union — A write operation to perform in a transaction. Can be an update, upsert, or remove command.
      - object — Command to update existing documents in a collection that match a query
        - `args` unknown
        - `collection` string, required — Name of the collection containing documents to update
        - `commands` UpdateCommand[], required — Array of update operations to apply to matching documents
          - `method` 'set' | 'setAttachment' | 'increment' | 'replaceWithCounter', required — Types of update operations that can be performed on document fields
          - `path` string, required — Path to the field to update within the document
          - `value` unknown, required
        - `query` string, required — Query expression that identifies which documents to update
        - `method` 'update', required
      - object — Command to insert a new document or update an existing one if it already exists
        - `collection` string, required — Name of the collection to upsert the document into
        - `id` unknown
        - `value` unknown, required
        - `valueTypeOverrides` object — Optional type overrides for specific fields in the document
        - `method` 'upsert', required
      - object — Command to remove documents or fields from a collection that match the specified query
        - `args` unknown
        - `collection` string, required — Name of the collection to remove documents from
        - `query` string, required — Query expression that identifies which documents to remove
        - `method` 'remove', required

## Response `200`

The write operations completed successfully. Returns results for each command, including the new transaction ID and counts of affected documents.

- WriteResponse — Response containing results of executing a write transaction
  - `results` WriteCommandResult[], required — Array of results for each write command executed in the transaction
    - union — Result of executing a write command. Contains the specific result type based on the command method.
      - object — Result of executing an update operation
        - `error` integer, required — Number of documents that failed to update due to errors
        - `internalError` integer — Number of documents that failed to update due to internal errors
        - `permissionDenied` integer — Number of documents that couldn't be updated due to insufficient permissions
        - `transactionId` integer, required — Transaction ID of the update operation
        - `updated` integer, required — Number of documents successfully updated
        - `method` 'update', required
      - object — Result of executing an upsert operation
        - `transactionId` integer, required — Transaction ID of the upsert operation
        - `method` 'upsert', required
      - object — Result of executing a remove operation
        - `deleted` integer, required — Number of documents successfully deleted
        - `internalError` integer — Number of documents that failed to delete due to internal errors
        - `permissionDenied` integer — Number of documents that couldn't be deleted due to insufficient permissions
        - `transactionId` integer, required — Transaction ID of the remove operation
        - `method` 'remove', required

## Other responses

- `400` — 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.
- `401` — Authentication failed. Verify that you're providing a valid API key or JWT token with appropriate write permissions for the affected collections.
- `403` — The authenticated user lacks permission to perform one or more of the requested write operations. Check your access control settings and ensure proper authorization.
- `500` — An unexpected server error occurred during the write operation. The transaction was rolled back to maintain consistency. Retry the request after a brief delay.

---

[API](https://skmtc.dev/ditto/apis/ditto-http-rpc-api.md) · [All operations](https://skmtc.dev/ditto/apis/ditto-http-rpc-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ditto/ditto-http-rpc-api/revisions/0f6d8b15f32d/schema)