> ## Documentation Index > Fetch the complete documentation index at: https://docs.myme.so/llms.txt > Use this file to discover all available pages before exploring further. # Apply a bulk action > Applies one action to every item matching a filter. Use to archive everything tagged `wip`, purge every trashed item older than 90 days, retier a slice of items, retag a source's items in bulk. Six actions, discriminated on `action`: `transition` (move to a target state), `purge` (hard-delete; admin-only; requires `confirm: PURGE`), `update_tags` (`add` / `remove`), `update_tier`, `update_properties` (shallow merge into properties), `update_timestamp`. Non-admin callers see their match set narrowed to types they hold write on. `purge` is admin-only regardless of filter. Safety rails: `dry_run: true` returns matched ids and count without writing; `max_items` caps the match set (default 10000, hard ceiling 50000); going over returns `400 bulk_cap_exceeded`. See [Bulk operations](/api/bulk-operations). ## OpenAPI ````yaml /openapi.json post /items/bulk_action openapi: 3.1.0 info: title: Marfa API version: 4.2.0 description: Typed data layer for structured personal data servers: [] security: [] paths: /items/bulk_action: post: tags: - Items summary: Apply a bulk action description: >- Applies one action to every item matching a filter. Use to archive everything tagged `wip`, purge every trashed item older than 90 days, retier a slice of items, retag a source's items in bulk. Six actions, discriminated on `action`: `transition` (move to a target state), `purge` (hard-delete; admin-only; requires `confirm: PURGE`), `update_tags` (`add` / `remove`), `update_tier`, `update_properties` (shallow merge into properties), `update_timestamp`. Non-admin callers see their match set narrowed to types they hold write on. `purge` is admin-only regardless of filter. Safety rails: `dry_run: true` returns matched ids and count without writing; `max_items` caps the match set (default 10000, hard ceiling 50000); going over returns `400 bulk_cap_exceeded`. See [Bulk operations](/api/bulk-operations). operationId: applyABulkAction requestBody: content: application/json: schema: oneOf: - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - transition state: type: string enum: - active - archived - trashed required: - action - state - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - purge confirm: type: string enum: - PURGE required: - action - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - update_tags add: type: array items: type: string remove: type: array items: type: string required: - action - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - update_tier tier: type: string enum: - library - feed required: - action - tier - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - update_properties patch: type: object additionalProperties: nullable: true required: - action - patch - type: object properties: filter: type: object properties: type: type: string state: type: string enum: - active - archived - trashed source: type: string tier: type: string enum: - library - feed tags: type: array items: type: string since: type: string until: type: string filter: type: string dry_run: type: boolean max_items: type: integer minimum: 0 exclusiveMinimum: true emit_events: type: boolean action: type: string enum: - update_timestamp timestamp: type: string required: - action - timestamp responses: '200': description: Dry-run result (synchronous; non-dry-run goes async) content: application/json: schema: type: object properties: action: type: string matched: type: integer succeeded: type: integer errored: type: integer dry_run: type: boolean ids: type: array items: type: string errors: type: array items: type: object properties: id: type: string code: type: string message: type: string required: - id - code - message blob_hashes_referenced: type: integer required: - action - matched - succeeded - errored - dry_run '202': description: >- Job queued. Poll GET /items/bulk_action/jobs/{id} until status is terminal (completed / failed / cancelled). SDKs do this transparently for callers; the envelope is exposed for explicit-control use cases. content: application/json: schema: type: object properties: id: type: string action: type: string status: type: string enum: - queued - in_progress - completed - failed - cancelled matched: type: integer processed: type: integer succeeded: type: integer errored: type: integer started_at: type: string finished_at: type: string error: type: string result: type: object properties: action: type: string matched: type: integer succeeded: type: integer errored: type: integer dry_run: type: boolean ids: type: array items: type: string errors: type: array items: type: object properties: id: type: string code: type: string message: type: string required: - id - code - message blob_hashes_referenced: type: integer required: - action - matched - succeeded - errored - dry_run required: - id - action - status - matched - processed - succeeded - errored '400': description: Validation error, missing confirm, or cap exceeded content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - missing_required_field - bulk_confirmation_required - bulk_cap_exceeded message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error '403': description: Admin required (purge only) content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - forbidden message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key or OAuth Token description: Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...) ````