Preview a batch asset field edit
POST /batch/asset-fields/preview
Previews a change to one metadata field across a selection of assets and posts.
You need assets.metadata.bulk_edit, either for the whole install or for at least one team. For each target, that permission must cover the target’s team, and you must own the asset or hold the applicable assets.admin permission; an asset with no team needs the bulk permission for the whole install. If the field sets a write_capability, you need it for the whole install. Its read_capability can be held for the whole install or for the asset’s team. system.admin works as the usual wildcard. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401.
Pick an asset field and one mode: overwrite, fill_empties, append or remove. Append and remove work only on multi_select fields. Archived, read-only and mirrored fields are refused, but deprecated ones still work. A missing field or a collection field returns 404. Display conditions and placement hints neither allow nor block this edit.
Send typed {kind, id} selection entries, where kind is asset or post. The server expands readable, live posts into their live member assets, removes duplicates and sorts the target IDs. Unreadable or missing posts contribute nothing and aren’t listed as empty; readable posts with no live members appear in empty_posts. A direct asset ID stays a target even when it’s missing or you can’t edit it, and both cases land in the same unauthorized partition. Collections aren’t supported.
The intended limits are 500 selection entries and 1,000 distinct expanded targets. The entry limit is checked before any membership reads, and going over it returns 422 with no token. Counting and expanding posts are separate reads, though, so concurrent membership changes can push the returned set past the intended target limit or leave members out. Apply uses the returned target set, not a fresh expansion.
Every returned target is in exactly one partition: would_change, no_op, refused, inapplicable, unreadable or unauthorized. eligible is would_change + no_op, and expanded is the sum of all six. Unreadable targets show no stored value or timestamp. Overwrite counts an authorized set as a change even when the value is identical, because it still advances the timestamp and adds history; other modes can leave targets unchanged. Removing the last term from a required field is refused for that target, while on an optional field it deletes the value row. There’s no general clear mode.
Preview sanitizes rich text and resolves vocabulary input before partitioning. It creates no field values, terms or audit event, but it does store a preview record. The opaque token binds the caller, canonical input, field fingerprints and ordered targets for 15 minutes; pass it to apply unchanged and don’t parse it. A successful preview also tries to purge records more than 24 hours past expiry, which is best-effort housekeeping, not a retention deadline. A valid non-empty selection can produce zero targets or zero proposed changes and still get a token.
This isn’t a locked snapshot. Preview uses cached field definitions and request-time capabilities, with separate subject and value reads. Apply runs its own checks, so a successful preview neither grants permission to write later nor promises that every proposed change will commit.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”Preview input: field, mode, canonicalizable value and typed selection. The reason and confirmation belong to apply, not preview.
object
How to edit each eligible target:
overwritesets the proposed value even when it equals the stored value, advancingset_atand adding history. Such a target iswould_change, notno_op.fill_emptiessets only semantically empty values; false and numeric zero are real values. An empty proposed value is refused even on an optional field.appendadds missing canonical terms, retaining existing order and then incoming order.removeremoves matching terms; unmatched terms are a no-op. Removing every term from an optional field deletes its value row; emptying a required field is refused for that target.
Append and remove are multi_select only. There is no general clear mode. Overwriting an optional text-shaped field with an explicitly empty string stores a value row rather than deleting it.
UUID of an asset-field definition. A missing definition or a collection-scoped definition is not found on this endpoint.
From 1 through 500 typed entries. The entry limit precedes membership queries; the server counts distinct expanded targets against an intended limit of 1,000 before a separate bounded expansion read.
Typed selection item. The client sends both kind and UUID; the server does not guess whether an ID names an asset or a post.
object
Asset names a direct target. post is expanded through readable, live post membership into live assets. Collections are not supported.
UUID interpreted according to kind. The same UUID may be supplied under both kinds; final asset targets are deduplicated.
Supply the member matching the field type: text, longtext, rich_text, select and tree use value_text; number and boolean use value_num; date and datetime use value_date; multi_select uses a non-empty value_options array; reference uses value_ref. Boolean values must be numeric 0 or 1. Every type requires its corresponding member, including an explicit string for text-shaped types. Send only that member; extra valid typed members are ignored by the value builder, although the decoder still checks their types.
Rich text is sanitized before emptiness is tested. Input patterns are enforced for text and longtext only; ordinary text is not trimmed. An optional overwrite can store an empty text value; required overwrites and every empty fill proposal are refused. For optional select/tree overwrite, "" bypasses vocabulary matching; a non-empty whitespace-only string is refused. Append/remove are multi_select only. A non-empty array containing only unusable terms can still fail vocabulary validation.
Normal vocabulary writes resolve slugs, labels, casing variants, aliases and merged-term chains, deduplicate canonical slugs and retain order. Only open multi_select fields can grow new terms, requiring global fields.vocabulary.extend. Remove matches without minting and can remove retired terms; unresolvable terms pass through for matching rather than causing an unknown-term refusal. Dates and datetimes use date-time strings, not date-only input.
object
String for text, longtext, rich_text, select or tree. Required for those types, even when explicitly empty. Only rich_text is sanitized; vocabulary types undergo their own resolution.
Number for number fields, or numeric 0/1 for boolean. Required for those types; false is not empty. The generated request model uses single-precision floating point before storage.
Date-time string for date or datetime fields. Required for those types.
Non-empty array of input terms for multi_select. Vocabulary resolution and mode-specific matching determine the canonical result. An empty array is not a clear request.
UUID for a reference field. Required for that type. Preview checks existence and absence of soft deletion, without a separate referenced-asset visibility check; archived references remain valid.
Responses
Section titled “ Responses ”Preview computed and its token record stored. No field value, vocabulary term or audit event was created.
Computed preview and its single-use token. The server stores a preview record, but creates no field value, vocabulary term or audit event.
object
Opaque caller-bound token for apply. Clients must pass it intact and must not parse its structure. It grants no authority by itself.
Preview expiry, normally 15 minutes after token creation. Apply checks it before starting its transaction, not again after lock waits or at commit.
UUID of the preview record, also used to identify the apply’s audit envelope.
Resolved operation mode, echoed for display. Apply reads this from the stored preview.
Selected asset-field definition UUID.
Field code seen at preview.
Field type used to interpret the proposed value.
Canonical proposed input after sanitizing and vocabulary resolution. Append and remove combine it with each target’s previewed set, so it isn’t necessarily each target’s final value.
object
String for text, longtext, rich_text, select or tree. Required for those types, even when explicitly empty. Only rich_text is sanitized; vocabulary types undergo their own resolution.
Number for number fields, or numeric 0/1 for boolean. Required for those types; false is not empty. The generated request model uses single-precision floating point before storage.
Date-time string for date or datetime fields. Required for those types.
Non-empty array of input terms for multi_select. Vocabulary resolution and mode-specific matching determine the canonical result. An empty array is not a clear request.
UUID for a reference field. Required for that type. Preview checks existence and absence of soft deletion, without a separate referenced-asset visibility check; archived references remain valid.
Canonical slugs that may be created on an open multi_select field if a successful apply write stores them. Listing them creates nothing; omitted when none are proposed.
Number of entries sent, before expansion and duplicate removal.
Distinct readable selected posts found to have no live members. Omitted when none are reported; inaccessible or missing posts are not disclosed here.
Preview counts: expanded is the sum of the six partitions; eligible equals would_change plus no_op. Apply returns these original counts alongside separate outcome counts.
object
Distinct target IDs returned by preview, including unauthorized direct asset IDs. Readable empty posts contribute no targets.
Would_change plus no_op. This is not the confirmation count.
Proposed writes or removals. Overwrite counts identical-value sets because they still update metadata and history. Apply can skip candidates that no longer qualify.
Eligible targets whose values this mode leaves unchanged. Overwrite does not use this partition.
Targets refused by a target-specific required-field or retired-term rule.
Targets whose asset type is outside the field’s applicability at preview.
Targets that fail the field-read capability gate after the earlier subject and applicability checks.
Absent, soft-deleted, outside bulk scope or not editable under the ordinary subject rule, without distinguishing those cases.
Every expanded target, sorted by asset ID, with one preview partition each. Membership changes during the separate expansion reads can affect this set.
One target’s preview partition. Only would_change targets can carry an existing value’s set_at timestamp; unreadable targets show no value details.
object
UUID of the expanded or directly selected target.
Preview classification for a target, with exactly one label per returned asset:
would_change: a candidate for a guarded write at apply, not a guarantee of success.no_op: eligible, but this mode leaves its value unchanged.refused: a target-specific required-field or retired-term rule refuses the change.inapplicable: the field does not cover the asset type seen at preview.unreadable: the caller cannot read this field on the subject; no stored value or timestamp is returned.unauthorized: absent or soft-deleted, outside bulk scope, or not editable under the ordinary owner/administrator rule.
Only would_change targets are considered for writes by apply. The other partitions remain preview observations.
Target-specific reason when partition is refused; omitted otherwise.
The existing value row’s set_at for a would_change target. Absent when there’s no value row, and on every other partition. Apply uses the guard stored with the token, so you don’t send this back.
The decoded request has an unsupported mode or selection kind, an empty selection or a value with the wrong shape. Malformed JSON is handled separately by the request decoder.
Structured refusal used by both endpoints, except the ordinary 401 and preview 404 responses. This request makes no new committed field changes, terms, audit envelope or token consumption. It does not restore an already spent, expired or removed preview.
object
Human-readable explanation of this refusal.
Machine-readable reason for a batch refusal. It complements the HTTP status.
400: empty_selection, unknown_mode, unknown_selection_kind, value_type_mismatch, token_required, reason_payload_too_large, reason_required, reason_too_long, confirm_count_invalid, confirm_count_required, confirm_count_not_applicable, confirm_count_mismatch.
403: preview_token_invalid, bulk_capability_required, field_write_capability_required, vocabulary_extend_required.
422 at preview: field_archived, field_read_only, field_mirrored, mode_not_supported_for_type, pattern_mismatch, required_value_empty, fill_empties_value_empty, unknown_slug, archived_slug, dangling_reference, selection_entry_ceiling, expanded_target_ceiling.
409 at apply: preview_consumed, preview_expired, definition_drift, vocabulary_drift, reference_invalidated.
dangling_reference means the proposed asset did not resolve at preview; reference_invalidated means it no longer resolves at the locked apply check. Missing or collection-scoped field definitions use the ordinary 404 body instead of this reason enum. Generated JSON/type decoding errors may use a plain-text 400 rather than this body. Unexpected internal errors are not batch refusals.
Field code when supplied by the refusing check; otherwise omitted.
Vocabulary slug associated with the refusal, when supplied; otherwise omitted.
Required confirmation count or applicable ceiling, when a numeric comparison is reported.
Supplied confirmation count or measured selection size for that comparison.
Original selection-entry count on an expanded_target_ceiling refusal, so a few posts expanding to many assets can be distinguished from many direct selections.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}You lack the bulk tool permission, the field’s write capability for the whole install, or permission to create a proposed vocabulary term.
Structured refusal used by both endpoints, except the ordinary 401 and preview 404 responses. This request makes no new committed field changes, terms, audit envelope or token consumption. It does not restore an already spent, expired or removed preview.
object
Human-readable explanation of this refusal.
Machine-readable reason for a batch refusal. It complements the HTTP status.
400: empty_selection, unknown_mode, unknown_selection_kind, value_type_mismatch, token_required, reason_payload_too_large, reason_required, reason_too_long, confirm_count_invalid, confirm_count_required, confirm_count_not_applicable, confirm_count_mismatch.
403: preview_token_invalid, bulk_capability_required, field_write_capability_required, vocabulary_extend_required.
422 at preview: field_archived, field_read_only, field_mirrored, mode_not_supported_for_type, pattern_mismatch, required_value_empty, fill_empties_value_empty, unknown_slug, archived_slug, dangling_reference, selection_entry_ceiling, expanded_target_ceiling.
409 at apply: preview_consumed, preview_expired, definition_drift, vocabulary_drift, reference_invalidated.
dangling_reference means the proposed asset did not resolve at preview; reference_invalidated means it no longer resolves at the locked apply check. Missing or collection-scoped field definitions use the ordinary 404 body instead of this reason enum. Generated JSON/type decoding errors may use a plain-text 400 rather than this body. Unexpected internal errors are not batch refusals.
Field code when supplied by the refusing check; otherwise omitted.
Vocabulary slug associated with the refusal, when supplied; otherwise omitted.
Required confirmation count or applicable ceiling, when a numeric comparison is reported.
Supplied confirmation count or measured selection size for that comparison.
Original selection-entry count on an expanded_target_ceiling refusal, so a few posts expanding to many assets can be distinguished from many direct selections.
Resource not found
object
Human-readable error summary
Example
the request could not be completedThe field, value, mode or measured selection size is refused. No preview token is issued.
Structured refusal used by both endpoints, except the ordinary 401 and preview 404 responses. This request makes no new committed field changes, terms, audit envelope or token consumption. It does not restore an already spent, expired or removed preview.
object
Human-readable explanation of this refusal.
Machine-readable reason for a batch refusal. It complements the HTTP status.
400: empty_selection, unknown_mode, unknown_selection_kind, value_type_mismatch, token_required, reason_payload_too_large, reason_required, reason_too_long, confirm_count_invalid, confirm_count_required, confirm_count_not_applicable, confirm_count_mismatch.
403: preview_token_invalid, bulk_capability_required, field_write_capability_required, vocabulary_extend_required.
422 at preview: field_archived, field_read_only, field_mirrored, mode_not_supported_for_type, pattern_mismatch, required_value_empty, fill_empties_value_empty, unknown_slug, archived_slug, dangling_reference, selection_entry_ceiling, expanded_target_ceiling.
409 at apply: preview_consumed, preview_expired, definition_drift, vocabulary_drift, reference_invalidated.
dangling_reference means the proposed asset did not resolve at preview; reference_invalidated means it no longer resolves at the locked apply check. Missing or collection-scoped field definitions use the ordinary 404 body instead of this reason enum. Generated JSON/type decoding errors may use a plain-text 400 rather than this body. Unexpected internal errors are not batch refusals.
Field code when supplied by the refusing check; otherwise omitted.
Vocabulary slug associated with the refusal, when supplied; otherwise omitted.
Required confirmation count or applicable ceiling, when a numeric comparison is reported.
Supplied confirmation count or measured selection size for that comparison.
Original selection-entry count on an expanded_target_ceiling refusal, so a few posts expanding to many assets can be distinguished from many direct selections.