Skip to content

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.

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

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.

string
reason
required

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.

string
<= 2000 characters
confirm_count

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.

integer
nullable <= 1000

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

Preview-record UUID identifying this operation and its audit envelope.

string format: uuid
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

Field-definition UUID bound into the preview.

string format: uuid
field_code
required

Code from the locked field definition used by apply.

string
counts
required

Original preview partitions, retained even when apply outcomes differ.

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

Outcomes for the preview’s would_change subset in a committed response.

object
changed
required

Targets whose set or removal succeeded.

integer
conflict
required

Targets whose expected value-row presence or set_at guard did not match.

integer
gone
required

Targets that are absent or soft-deleted at the locked subject check.

integer
unauthorized_at_apply
required

Targets that fail a current per-target permission check.

integer
error
required

Reserved outcome count. Currently zero in a successful response: unexpected apply errors abort the transaction.

integer
targets
required

Each preview would_change target and its apply outcome, retaining their relative asset-ID order. Other preview partitions are not repeated here.

Array<object>

Apply outcome for one preview would_change target.

object
asset_id
required

UUID of the target asset.

string format: uuid
outcome
required

Outcome for one preview would_change target:

  • changed: the guarded set or removal succeeded.
  • conflict: the expected row presence or set_at guard 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.

string
Allowed values: changed conflict gone unauthorized_at_apply error
unauthorized_reason

Which current per-target check failed. Present only for unauthorized_at_apply; otherwise omitted.

string
Allowed values: bulk_scope subject_authority unreadable
committed_terms

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.

Array<string>

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
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"
}

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

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

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