Skip to content

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.

Preview input: field, mode, canonicalizable value and typed selection. The reason and confirmation belong to apply, not preview.

object
mode
required

How to edit each eligible target:

  • overwrite sets the proposed value even when it equals the stored value, advancing set_at and adding history. Such a target is would_change, not no_op.
  • fill_empties sets only semantically empty values; false and numeric zero are real values. An empty proposed value is refused even on an optional field.
  • append adds missing canonical terms, retaining existing order and then incoming order.
  • remove removes 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.

string
Allowed values: overwrite fill_empties append remove
field_id
required

UUID of an asset-field definition. A missing definition or a collection-scoped definition is not found on this endpoint.

string format: uuid
selection
required

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.

Array<object>
>= 1 items

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
kind
required

Asset names a direct target. post is expanded through readable, live post membership into live assets. Collections are not supported.

string
Allowed values: asset post
id
required

UUID interpreted according to kind. The same UUID may be supplied under both kinds; final asset targets are deduplicated.

string format: uuid
value
required

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
value_text

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.

string
nullable
value_num

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.

number
nullable
value_date

Date-time string for date or datetime fields. Required for those types.

string format: date-time
nullable
value_options

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.

Array<string>
nullable
value_ref

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.

string format: uuid
nullable

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
token
required

Opaque caller-bound token for apply. Clients must pass it intact and must not parse its structure. It grants no authority by itself.

string
expires_at
required

Preview expiry, normally 15 minutes after token creation. Apply checks it before starting its transaction, not again after lock waits or at commit.

string format: date-time
operation_id
required

UUID of the preview record, also used to identify the apply’s audit envelope.

string format: uuid
mode
required

Resolved operation mode, echoed for display. Apply reads this from the stored preview.

string
Allowed values: overwrite fill_empties append remove
field_id
required

Selected asset-field definition UUID.

string format: uuid
field_code
required

Field code seen at preview.

string
field_type
required

Field type used to interpret the proposed value.

string
resolved_value
required

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
value_text

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.

string
nullable
value_num

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.

number
nullable
value_date

Date-time string for date or datetime fields. Required for those types.

string format: date-time
nullable
value_options

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.

Array<string>
nullable
value_ref

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.

string format: uuid
nullable
mintable_terms

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.

Array<string>
selection_entry_count
required

Number of entries sent, before expansion and duplicate removal.

integer
empty_posts

Distinct readable selected posts found to have no live members. Omitted when none are reported; inaccessible or missing posts are not disclosed here.

Array<string>
counts
required

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
expanded
required

Distinct target IDs returned by preview, including unauthorized direct asset IDs. Readable empty posts contribute no targets.

integer
eligible
required

Would_change plus no_op. This is not the confirmation count.

integer
would_change
required

Proposed writes or removals. Overwrite counts identical-value sets because they still update metadata and history. Apply can skip candidates that no longer qualify.

integer
no_op
required

Eligible targets whose values this mode leaves unchanged. Overwrite does not use this partition.

integer
refused
required

Targets refused by a target-specific required-field or retired-term rule.

integer
inapplicable
required

Targets whose asset type is outside the field’s applicability at preview.

integer
unreadable
required

Targets that fail the field-read capability gate after the earlier subject and applicability checks.

integer
unauthorized
required

Absent, soft-deleted, outside bulk scope or not editable under the ordinary subject rule, without distinguishing those cases.

integer
targets
required

Every expanded target, sorted by asset ID, with one preview partition each. Membership changes during the separate expansion reads can affect this set.

Array<object>

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
asset_id
required

UUID of the expanded or directly selected target.

string format: uuid
partition
required

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.

string
Allowed values: would_change no_op refused inapplicable unreadable unauthorized
refusal_reason

Target-specific reason when partition is refused; omitted otherwise.

string
Allowed values: required_would_empty vocabulary_retired_not_held
if_unchanged_since

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.

string format: date-time
nullable

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
error
required

Human-readable explanation of this refusal.

string
reason
required

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.

string
Allowed values: empty_selection unknown_mode unknown_selection_kind token_required reason_payload_too_large reason_required reason_too_long confirm_count_invalid confirm_count_required confirm_count_not_applicable confirm_count_mismatch preview_token_invalid preview_consumed preview_expired bulk_capability_required field_write_capability_required vocabulary_extend_required field_archived field_mirrored mode_not_supported_for_type required_value_empty fill_empties_value_empty unknown_slug archived_slug selection_entry_ceiling expanded_target_ceiling definition_drift vocabulary_drift reference_invalidated value_type_mismatch field_read_only pattern_mismatch dangling_reference
field

Field code when supplied by the refusing check; otherwise omitted.

string
nullable
option

Vocabulary slug associated with the refusal, when supplied; otherwise omitted.

string
nullable
expected

Required confirmation count or applicable ceiling, when a numeric comparison is reported.

integer
nullable
actual

Supplied confirmation count or measured selection size for that comparison.

integer
nullable
entry_count

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.

integer
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"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
error
required

Human-readable explanation of this refusal.

string
reason
required

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.

string
Allowed values: empty_selection unknown_mode unknown_selection_kind token_required reason_payload_too_large reason_required reason_too_long confirm_count_invalid confirm_count_required confirm_count_not_applicable confirm_count_mismatch preview_token_invalid preview_consumed preview_expired bulk_capability_required field_write_capability_required vocabulary_extend_required field_archived field_mirrored mode_not_supported_for_type required_value_empty fill_empties_value_empty unknown_slug archived_slug selection_entry_ceiling expanded_target_ceiling definition_drift vocabulary_drift reference_invalidated value_type_mismatch field_read_only pattern_mismatch dangling_reference
field

Field code when supplied by the refusing check; otherwise omitted.

string
nullable
option

Vocabulary slug associated with the refusal, when supplied; otherwise omitted.

string
nullable
expected

Required confirmation count or applicable ceiling, when a numeric comparison is reported.

integer
nullable
actual

Supplied confirmation count or measured selection size for that comparison.

integer
nullable
entry_count

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.

integer
nullable

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The 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
error
required

Human-readable explanation of this refusal.

string
reason
required

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.

string
Allowed values: empty_selection unknown_mode unknown_selection_kind token_required reason_payload_too_large reason_required reason_too_long confirm_count_invalid confirm_count_required confirm_count_not_applicable confirm_count_mismatch preview_token_invalid preview_consumed preview_expired bulk_capability_required field_write_capability_required vocabulary_extend_required field_archived field_mirrored mode_not_supported_for_type required_value_empty fill_empties_value_empty unknown_slug archived_slug selection_entry_ceiling expanded_target_ceiling definition_drift vocabulary_drift reference_invalidated value_type_mismatch field_read_only pattern_mismatch dangling_reference
field

Field code when supplied by the refusing check; otherwise omitted.

string
nullable
option

Vocabulary slug associated with the refusal, when supplied; otherwise omitted.

string
nullable
expected

Required confirmation count or applicable ceiling, when a numeric comparison is reported.

integer
nullable
actual

Supplied confirmation count or measured selection size for that comparison.

integer
nullable
entry_count

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.

integer
nullable