---
title: "Set or clear one field across many capsules, with a dry run that counts first"
method: POST
path: "/api/preview/capsules/batch/edit-fields"
tags: ["capsule"]
---

# Set or clear one field across many capsules, with a dry run that counts first

`POST /api/preview/capsules/batch/edit-fields`

## Request

- Base URL: `https://symbol.chat` (the document declares no server; this is the origin it was published from)
- URL: `https://symbol.chat/api/preview/capsules/batch/edit-fields`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-next-auth.session-token`
  - OAuth 2
    - Authorization code: `https://mcp.symbol.chat/authorize`
    - Token URL: `https://mcp.symbol.chat/token`

## Request body

- object
  - `action` 'set' | 'clear', required: `set` writes `value` to the field; `clear` removes the field's value.
  - `capsuleIds` string[], required: Capsule UUIDs to operate on
  - `dry_run` boolean: When true, nothing is written: the response reports, per capsule, what the edit would do.
  - `field` string, required: Name of the field to edit, as declared on each capsule's Type.
  - `value` union: The value to write for `set`, validated against the field's kind on each capsule's Type.
    - string
    - number
    - boolean
    - string[]
    - object[]
    - object: Image field value: an attachment reference (`{ attachment_id, alt }`).
      - `alt` string: Optional alt text — the accessibility backbone; rendered as the image `alt`.
      - `attachment_id` string, required: Id of the capsule attachment this image field points at.
    - object: File field value: an attachment reference (`{ attachment_id, label }`).
      - `attachment_id` string, required: Id of the capsule attachment this file field points at.
      - `label` string: Optional display label shown on the file chip in place of the raw file name.

## Response `200`

Successful response

- object: Result of a bulk field or tag edit, or its dry run.
  - `batch_id` string, nullable: UUID v4 string
  - `dry_run` boolean, required
  - `failed` object[], required
    - `code` string, required
    - `error` string, required
    - `id` string, required: UUID v4 string
  - `succeeded` object[], required
    - `changed` boolean, required: Whether this capsule's stored value (or tags) changes.
    - `id` string, required: UUID v4 string
    - `republish` union: Whether this write started a republish of the capsule's published skill.
      - object
        - `message` string, required: One sentence saying what happened to the published skill, and what to do next.
        - `status` 'started', required: This write started a republish, which completes on its own.
      - object
        - `message` string, required: One sentence saying what happened to the published skill, and what to do next.
        - `reason` 'opted_out' | 'caller_default' | 'blocked' | 'name_changed' | 'no_refresh_right' | 'rate_limited' | 'check_failed', required: `opted_out` (republish: false), `caller_default` (this caller does not republish unless asked), `blocked` (publishing is blocked for this capsule), `name_changed` (a republish would rename the skill), `no_refresh_right` (only someone who may share the capsule can republish it), `rate_limited` (the publish rate limit was reached), or `check_failed` (the republish could not be checked).
        - `status` 'not_started', required: The published skill was left stale, for the reason in `reason`.
    - `version_skip_reason` string, nullable: Why the revision was not recorded (for example `hourly_rate`); null when it was.
    - `version_skipped` boolean: True when the edit was saved without a revision (the version guard skipped it).
  - `summary` object, required
    - `changed` integer, required: Capsules that change (or would, on a dry run).
    - `refused` integer, required: Capsules the edit cannot apply to, listed in `failed`.
    - `unchanged` integer, required: Capsules already holding the result.

## Changes

- **2026-10-27** `3a2c4ebeab51`: 1 info
  - added the optional property `succeeded/items/republish` to the response with the `200` status
- **2026-10-19** `5778844d1f9e`: 3 info
  - added the optional property `batch_id` to the response with the `200` status
  - added the optional property `succeeded/items/version_skip_reason` to the response with the `200` status
  - added the optional property `succeeded/items/version_skipped` to the response with the `200` status
- **2026-09-30** `6a95af57f0f6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/capsules/batch/edit-fields/post.md)

---

[API](https://skmtc.dev/symbol/apis/symbol-api.md) - [All operations](https://skmtc.dev/symbol/apis/symbol-api/llms.txt) - [OpenAPI document](https://skmtc.dev/symbol/apis/symbol-api/revisions/3a2c4ebeab51?raw)