Apply a batch asset field edit
POST /batch/asset-fields/apply
Applies the proposed changes from a batch preview token issued earlier.
Sign in as the same account that requested the preview. Send the token, a reason and, for overwrite or remove, a confirm_count equal to the preview’s would_change count, even when that’s zero. Leave the count out for fill_empties and append; JSON null counts as left out. Apply takes the mode, field, canonical value and targets from the stored preview, so it doesn’t expand the selection again or accept replacements for any of them. 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.
The reason is required: at most 2,000 Unicode code points as sent, then trimmed to a non-empty value of at most 500 code points. The audit envelope records the trimmed text; it isn’t part of the preview binding.
Request-shape checks run first. For an otherwise valid request, a malformed token, an unknown token and another account’s token all get the same 403 preview_token_invalid body; that’s the same status and body, not a timing guarantee. For a token you own, the server checks consumption before expiry, then the mode-specific confirmation, the field and vocabulary fingerprints, current authority and reference liveness. An expired token normally gets 409 preview_expired, and an already consumed one 409 preview_consumed. A removed preview also becomes invalid. If it disappears between lookup and consumption you can get preview_consumed, which then doesn’t prove that an earlier apply succeeded.
Only preview targets marked would_change are considered for writing. Under locks, apply re-reads effective capabilities without the capability cache, checks the current owner, team, liveness and field readability, and validates the field and vocabulary fingerprints. The effective-capability query still counts expired grants or revokes until maintenance removes them. A changed definition or vocabulary fingerprint, or a proposed reference that no longer exists, refuses the whole batch. Archived assets stay live subjects and valid references; soft-deleted or missing subjects report gone.
A changed value timestamp or an unexpected present or absent row reports conflict, and lost scope, subject authority or readability reports unauthorized_at_apply. Other eligible targets can still change. The timestamp guard doesn’t compare the full stored value. Apply doesn’t recheck field applicability for a target whose asset type changed, and the definition fingerprint doesn’t cover open_vocabulary. Minting still checks that flag on the locked definition and can refuse with vocabulary_drift.
Before opening the transaction, apply looks up the token and checks the caller, prior consumption, expiry and confirmation. It then checks current state and performs the writes synchronously in one transaction. Successful field changes, their history, any new terms, token consumption and the production audit envelope commit together. Even with zero proposed writes, the batch-wide field, authority and proposed-reference checks still run. New terms are created only when a successful write stores them. The envelope records the reason, IDs and counts, not old or new field values. counts keeps the preview partitions, while targets and outcome_counts cover only the would_change subset. So a 200 can report partial success or zero changes and still consume the token and record the operation.
Unexpected database, history, search-rebuild or audit errors abort the whole transaction; the current implementation doesn’t turn them into per-target error outcomes. A refusal before commit makes no new durable changes and consumes nothing, but it can’t restore a token that’s already consumed, expired or removed. A lost response or commit error leaves you unsure whether the commit happened. Replaying doesn’t return the earlier result, so run a new preview on purpose before deciding on another operation.
There’s no job, live progress, way to cancel a running apply, or batch undo. Locks can make other writes wait, including writes to another field on a selected asset or to an asset that shares a containing post. The token’s expiry is checked before the transaction starts, not again after lock waits or at commit.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”Apply input: token, required reason and a mode-dependent confirmation count. Mode, value and targets come from the stored preview; additional JSON members are not rejected by the current decoder.
object
Opaque token returned by preview, used without parsing or alteration. An empty or omitted token returns token_required. Unrecognized or wrong-account tokens share the preview_token_invalid response.
Why this batch change is being made. At most 2,000 Unicode code points as sent, and 1 to 500 after trimming; the raw limit is checked first. The trimmed value is stored in the audit envelope and isn’t bound into the preview.
Required for overwrite and remove, and must equal the preview’s would_change count, even when that’s zero. Leave it out for fill_empties and append; JSON null counts as absent. The fixed range 0 to 1000 is checked before token lookup, and the mode-specific checks run after the token is matched to you. It confirms proposed writes, not how many will eventually succeed.
Responses
Section titled “ Responses ”The transaction committed. This can include skipped or conflicting targets and zero changed values; the token is consumed and the production audit envelope is recorded.
A committed apply result. In production, token consumption, successful field changes, history, newly created terms and one audit envelope commit in one transaction. Zero changed values is still a committed operation. The response is not stored as a separately replayable result.
object
Preview-record UUID identifying this operation and its audit envelope.
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.
Field-definition UUID bound into the preview.
Code from the locked field definition used by apply.
Original preview partitions, retained even when apply outcomes differ.
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.
Outcomes for the preview’s would_change subset in a committed response.
object
Targets whose set or removal succeeded.
Targets whose expected value-row presence or set_at guard did not match.
Targets that are absent or soft-deleted at the locked subject check.
Targets that fail a current per-target permission check.
Reserved outcome count. Currently zero in a successful response: unexpected apply errors abort the transaction.
Each preview would_change target and its apply outcome, retaining their relative asset-ID order. Other preview partitions are not repeated here.
Apply outcome for one preview would_change target.
object
UUID of the target asset.
Outcome for one preview would_change target:
changed: the guarded set or removal succeeded.conflict: the expected row presence orset_atguard did not match.gone: the subject is absent or soft-deleted; archive alone does not cause this.unauthorized_at_apply: the current bulk scope, subject authority or field-read check failed, with a sub-reason.error: included in the schema, but not currently emitted by the apply loop. Unexpected errors abort the whole transaction instead.
For a successful response, would_change = changed + conflict + gone + unauthorized_at_apply + error. None of the other preview partitions is retried by apply.
Which current per-target check failed. Present only for unauthorized_at_apply; otherwise omitted.
Canonical slugs actually created by this apply, sorted by slug. A new term is created only when a successful write stores it. The member is omitted when no terms were created.
The request shape, or the confirmation for your own token, is invalid. Malformed JSON is handled separately by the 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"}The token cannot be attributed to this caller, or current bulk, field-write or vocabulary-extension authority is insufficient.
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.
The caller-owned preview is consumed, expired or no longer matches a checked condition. Re-preview to plan another operation; a consumed response does not return the earlier result.
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.
A decoded request is refused on its merits. The current apply path does not ordinarily produce this response; its value and mode were validated at preview.
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.