Write table rows
Applies a batch of up to 1000 row operations to one table of an item, all of them or none. A batch that changes rows moves the item's last_activity_at to the batch's time, unless the item holds a later one, and sends one rows.changed event.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
id*stringThe ID of the item.
table*stringThe name of the table.
Idempotency-Key?stringA unique key that makes the request safe to retry. If you send the same request with the same key again, Marfa returns the first response and doesn't write again. A key belongs to the credential that sends it.
length <= 255application/json- body
A batch of row operations.
operations*array<>The operations, applied in order. A later operation on a row sees what an earlier one left. A whole number in values whose digits a 64-bit float doesn't keep is refused: send it as a string.
1 <= items <= 1000Returns the batch's ID and each operation's outcome, in order.
application/json- response
What a batch of row changes did.
batch*|The ID of the batch, or null when it changed no row.
last_activity_at*stringThe time of the batch, in UTC, which each row it changed took as its updated_at, or the item's own last_activity_at when the batch changed no row. An item that held a later last_activity_at keeps it.
results*array<>One entry per operation, in the order you sent them.
invalid_id: the ID is not a valid item ID.validation_error: an operation is malformed, names a column the table doesn't declare, breaks a column's rule, holds a whole number a 64-bit float can't keep or names an item you can't read, or the batch holds no operations or more than 1000.details.operationnames the operation.
application/json- response
An error response.
error*What went wrong.
unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.
application/json- response
An error response.
error*What went wrong.
type_not_permitted: you can't write the item's type, or your credential reaches no type.forbidden: aputorpatchnames a column whose value names an item you can't read.details.operationnames the operation anddetails.columnthe column.
application/json- response
An error response.
error*What went wrong.
item_not_found: no item has this ID, the item is in the trash (details.trashedistrueif you can read its type), or its type is one you can't read.row_not_found: apatchnames a row the table doesn't hold.details.operationnames it.table_not_found: the item's type declares no table of this name.
application/json- response
An error response.
error*What went wrong.
request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.
application/json- response
An error response.
error*What went wrong.
idempotency_key_in_flight: a request carrying the same Idempotency-Key is still being processed. Retry.
application/json- response
An error response.
error*What went wrong.
contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.
application/json- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- response
An error response.
error*What went wrong.
idempotency_contract_changed: the first response was made under another contract version, so Marfa can't replay it. The write isn't repeated.idempotency_key_reused: the key was first used for a different request. Nothing is written.idempotency_result_not_retained: the first response was too large to keep, so Marfa can't replay it. The write isn't repeated.
application/json- response
An error response.
error*What went wrong.
rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.
application/json- response
An error response.
error*What went wrong.
internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.
application/json- response
An error response.
error*What went wrong.
write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.
application/json- response
An error response.
error*What went wrong.
insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.
application/json- response
An error response.
error*What went wrong.
curl -X POST 'http://localhost:8600/items/string/tables/string/rows' \ -H 'Content-Type: application/json' \ -d '{ "operations": [ { "op": "put", "values": { "amount": 12.5, "memo": "Coffee" } }, { "op": "patch", "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f70", "values": { "memo": null } }, { "op": "delete", "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f71" } ]}'{ "batch": "019a5b1e-8b22-7c4d-9e5f-6a7b8c9d0e1f", "last_activity_at": "2026-10-03T09:30:00.000Z", "results": [ { "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f72", "outcome": "created" }, { "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f70", "outcome": "patched" }, { "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f71", "outcome": "absent" } ]}