Apply a bulk action
Applies one action to every item that matches a filter: change state, purge, update tags, tier, properties or own time. It matches only items you can write. With dry_run: true it returns the matched IDs; otherwise it queues a bulk-action job.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
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 <= 255X-Marfa-Instance-Id?stringThe ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- body
filter?Which items a bulk action applies to. Each field narrows the match as the same filter does on GET /items.
dry_run?booleanmax_items?integerThe most items the action may match. Defaults to 10,000. A value above 50,000 counts as 50,000.
0 < valueenable_fanout?booleanaction*"transition""transition"state*string"active""archived""trashed"Dry run: returns matched and the matched ids without writing anything. A purge dry run also lists matches that aren't in the trash. The purge skips those.
application/json- response
What a bulk action did, or for a dry run, what it matched.
action*stringThe action, such as purge.
matched*integerHow many items the action matched.
succeeded*integerHow many items the action changed. 0 on a dry run.
errored*integerHow many matched items the action left unchanged. 0 on a dry run.
dry_run*booleantrue if this was a dry run, which changed nothing.
ids?array<string>On a dry run, the ID of every matched item. On a job, the IDs of the items it changed, if it changed from 1 to 100 of them; absent otherwise.
errors?array<>On a job, the first 100 items it left unchanged, each with its error. Absent otherwise.
blob_hashes_referenced?integerOn a purge job, how many distinct blobs the purged items referenced, whether or not anything still references them. Absent otherwise.
settings?array<>On a type move, every folder, view and webhook setting that named the old type when the job finished. Absent otherwise.
remaining?integerOn a type move, how many items you can see are still of the old type when the job finished, in any state: those it left unchanged and any written since the move began. Absent otherwise.
remaining_hidden?booleanOn a type move, true if items your source filter hides are still of the old type. A move takes only items you can see. Absent otherwise.
settings_rewritten?booleanOn a type move, true if Marfa rewrote settings to name the new type. false if an item of the old type remains, a setting has a reason, or settings_error names a refusal; then none was rewritten. Absent otherwise.
settings_error?On a type move, why Marfa rewrote none of settings once no item of the old type remained: the new type is gone, or a folder or view would refuse its rewrite. Change the setting or register the type, then run the move again. Absent otherwise.
Returns the queued job. Poll GET /items/bulk-actions/jobs/{id} until status is completed, failed or canceled. The job acts for your credential as it stands. If your key is revoked or expires, your app's access is revoked, or a purge loses items.purge, the job ends failed and keeps its result.
application/json- response
A bulk action Marfa runs in the background, with its progress.
id*stringUnique identifier for the job.
action*stringThe action, such as purge.
status*stringWhere the job is.
"queued""in_progress""completed""failed""canceled"matched*integerHow many items the job acts on, fixed when Marfa queued it.
processed*integerHow many of the matched items the job has reached so far, changed or not.
succeeded*integerHow many items the job has changed so far.
errored*integerHow many items the job has left unchanged so far.
started_at?stringWhen the job started running, in UTC. Absent until then.
finished_at?stringWhen the job completed, failed or was canceled, in UTC. Absent until then.
error?stringWhy the job failed, for a person to read. Present only when status is failed.
result?What the job did. Present once status is completed or failed.
validation_error: the body is malformed or has an undeclared or empty field, orupdate_tagshas noaddorremove.missing_required_field: a needed field is missing.invalid_properties:patchholds a whole number a 64-bit float cannot keep.bulk_confirmation_required: a purge withoutconfirm: "PURGE".bulk_cap_exceeded: more items match thanmax_itemsallows.
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.
forbidden: you don't haveitems.purgefor a purge, or the instance's source filter changed while Marfa selected items. Repeat the request.type_not_permitted: your credential reaches no type, orfilter.typeis a type you can't read.edge_type_not_permitted: the filter names an edge type you can't read.
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.
instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.
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/bulk-actions' \ -H 'Content-Type: application/json' \ -d '{ "action": "transition", "state": "active"}'{ "action": "update_tags", "matched": 1, "succeeded": 0, "errored": 0, "dry_run": true, "ids": [ "01a1011a-4902-76cf-a4a9-88e99c038c8d" ]}