Bulk actions

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.

POST
/items/bulk-actions

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

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
X-Marfa-Instance-Id?string

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

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body
filter?

Which items a bulk action applies to. Each field narrows the match as the same filter does on GET /items.

dry_run?boolean
max_items?integer

The most items the action may match. Defaults to 10,000. A value above 50,000 counts as 50,000.

Range0 < value
enable_fanout?boolean
action*"transition"
Value in"transition"
state*string
Value in"active""archived""trashed"

Response body

About errors

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

What a bulk action did, or for a dry run, what it matched.

action*string

The action, such as purge.

matched*integer

How many items the action matched.

succeeded*integer

How many items the action changed. 0 on a dry run.

errored*integer

How many matched items the action left unchanged. 0 on a dry run.

dry_run*boolean

true 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?integer

On 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?integer

On 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?boolean

On 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?boolean

On 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
  1. response

A bulk action Marfa runs in the background, with its progress.

id*string

Unique identifier for the job.

action*string

The action, such as purge.

status*string

Where the job is.

Value in"queued""in_progress""completed""failed""canceled"
matched*integer

How many items the job acts on, fixed when Marfa queued it.

processed*integer

How many of the matched items the job has reached so far, changed or not.

succeeded*integer

How many items the job has changed so far.

errored*integer

How many items the job has left unchanged so far.

started_at?string

When the job started running, in UTC. Absent until then.

finished_at?string

When the job completed, failed or was canceled, in UTC. Absent until then.

error?string

Why 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, or update_tags has no add or remove.
  • missing_required_field: a needed field is missing.
  • invalid_properties: patch holds a whole number a 64-bit float cannot keep.
  • bulk_confirmation_required: a purge without confirm: "PURGE".
  • bulk_cap_exceeded: more items match than max_items allows.
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.

  • forbidden: you don't have items.purge for a purge, or the instance's source filter changed while Marfa selected items. Repeat the request.
  • type_not_permitted: your credential reaches no type, or filter.type is a type you can't read.
  • edge_type_not_permitted: the filter names an edge type you can't read.
application/json
  1. 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
  1. 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
  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.

request_too_large: the request body is larger than this instance accepts.

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/bulk-actions' \  -H 'Content-Type: application/json' \  -d '{  "action": "transition",  "state": "active"}'
About errors
{  "action": "update_tags",  "matched": 1,  "succeeded": 0,  "errored": 0,  "dry_run": true,  "ids": [    "01a1011a-4902-76cf-a4a9-88e99c038c8d"  ]}