Tables

Undo a table batch

Puts back every row a batch changed as it was before the batch, as a new batch, all or none. Undo an undo to redo it. Sends one rows.changed event that names the undone batch in undoes.

POST
/items/{id}/tables/{table}/batches/{batch}/undo

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Path parameters

id*string

The ID of the item.

table*string

The name of the table.

batch*string

The ID of the batch.

Header parameters

Idempotency-Key?string

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

Lengthlength <= 255

Response body

About errors

Returns the undo's batch ID and what it did to each row.

application/json
  1. response

What an undo did.

batch*|

The ID of the undo's own batch, or null when every row already stood as it was before the undone batch. Undo this batch to redo the one it undid.

undoes*string

The ID of the batch you undid.

last_activity_at*string

The time of the undo, in UTC, which each row it changed took as its updated_at, or the item's own last_activity_at when the undo changed no row. An item that held a later last_activity_at keeps it.

results*array<>

One entry per row the undone batch changed, by ID.

  • invalid_id: the ID is not a valid item ID.
  • validation_error: a query parameter is unknown.
application/json
  1. 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
  1. 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: a row the batch changed, other than one it created, names an item you can't read in a column, now, before the batch or after it. details.row names the row and details.column the column.
application/json
  1. response

An error response.

error*

What went wrong.

  • item_not_found: no item has this ID, the item is in the trash (details.trashed is true if you can read its type), or its type is one you can't read.
  • batch_not_found: the table's change log holds no batch with this ID. It may be older than row_log_retention_days.
  • table_not_found: the item's type declares no table of this name.
application/json
  1. response

An error response.

error*

What went wrong.

  • undo_conflict: a later batch changed rows the undo would put back. details.rows names them. Undo the later batches first, newest first.
  • idempotency_key_in_flight: a request carrying the same Idempotency-Key is still being processed. Retry.
application/json
  1. 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
  1. 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
  1. 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
  1. 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
  1. 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
  1. 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
  1. response

An error response.

error*

What went wrong.

curl -X POST 'http://localhost:8600/items/string/tables/string/batches/string/undo'
About errors
{  "batch": "019a5b1e-9c33-7e5f-8a6b-7c8d9e0f1a2b",  "undoes": "019a5b1e-8b22-7c4d-9e5f-6a7b8c9d0e1f",  "last_activity_at": "2026-10-03T09:31:00.000Z",  "results": [    {      "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f70",      "outcome": "replaced"    },    {      "id": "019a5b1e-7c41-7d2e-9f3a-5b8c2d4e6f72",      "outcome": "deleted"    }  ]}