---
title: "Update a capsule"
method: PUT
path: "/api/preview/capsules/{id}"
tags: ["capsule"]
---

# Update a capsule

`PUT /api/preview/capsules/{id}`

## Path parameters

- `id` string, required — UUID v4 string

## Request body

- object
  - `agent` boolean — Package this capsule as a Claude Code agent (`true`) or stop packaging it (`false`). Omit to leave unchanged. An agent's system prompt is its resolved body — its authored markdown, or its Type's `output_template` when it borrows one, with its field values composed in whenever the Type declares fields (those fields are prompt inputs, not dropped data); its alias is its name, and its summary is its description; encrypted capsules can't be agents.
  - `agent_meta` object, nullable — First-class agent authoring metadata (subagent name, description, and per-key frontmatter overrides). Omit to leave unchanged; send `null` to clear. Overrides the capsule's slug/summary/field_values fallbacks.
    - `description` string, nullable — Subagent description; overrides the capsule summary as the agent frontmatter `description`.
    - `frontmatter` object, nullable — Per-key agent frontmatter overrides (e.g. `model`, `tools`). Each key must be an allowlisted agent frontmatter field (validated server-side). Values are scalars or lists of strings — never nested objects.
    - `name` string, nullable — Explicit subagent name; overrides the capsule alias (slug). Lowercase letters, digits, and single hyphens (validated server-side).
  - `categories` string[] — Replace the capsule's categories. Omit to leave unchanged; send `[]` to clear. Slugs from the curated taxonomy; unknown slugs 400.
  - `cek_params` object — Opaque CEK metadata produced by the client crypto layer
  - `client_updated_at` string, date-time — Optimistic-concurrency token. ISO-8601 datetime WITH offset (`Z` or `±HH:MM`); pass the value returned by `get_capsule`'s `updated_at` field verbatim. (Tightened from legacy: bare ISO without offset is now rejected as a 422 instead of silently bypassing OCC.) If the server's stored updated_at differs, the request 409s.
  - `content_md` string, nullable — Markdown body (source of truth). Omit to leave unchanged; send an empty string to clear it (the blank is honoured — the Type template is NOT re-inherited); send `null` to revert to borrowing the Type's output template live (un-fork), which also resets `token_bindings`. Maximum length is configured per-Type via `content_md_max` (default 20000, ceiling 90000).
  - `field_values` object — Replace the capsule's structured field values. Omit to leave unchanged; send `{}` to clear. Validated against the Type's `field_schema`.
  - `incomplete` boolean — Set the capsule's `incomplete` state (issue #1703). Send `false` to complete it — the Type's required fields are enforced at that moment and completion fails naming any still missing; send `true` to re-open it. Omit to leave unchanged.
  - `is_encrypted` boolean — One-way: set to `true` to enable E2EE on this capsule. Cannot be reverted to `false`.
  - `is_prompt` boolean — Expose this capsule on the MCP `prompts` surface, or remove it. Toggling does not move the capsule or change its `@type/ref`. Omit to leave unchanged.
  - `project_id` string, nullable — UUID v4 string
  - `prompt_meta` object, nullable — First-class prompt presentation metadata (target model slugs, how-to-use, expected output, edit prompt). Omit to leave unchanged; send `null` to clear. Independent of the Type's field schema.
    - `editPrompt` string — A companion prompt for editing/iterating (paragraph).
    - `expectedOutput` string — What output to expect (paragraph).
    - `howToUse` string — How to use this prompt (paragraph).
    - `models` string[] — Curated target-model slugs from the models registry. Validated against the registry server-side; unknown slugs are rejected.
  - `republish` boolean — For a capsule published as a skill: whether editing it auto-republishes the skill so the served content follows the edit (default `true`). Send `false` to leave the published skill stale and republish manually. No effect on capsules that aren't published skills.
  - `share_display` 'article' | 'prompt' | 'showcase', nullable — How this capsule renders on its public share page: `article`, `prompt`, or `showcase`. Omit (or send `null` on update) to INHERIT the Type's `share_template` live; a concrete value pins it permanently. Independent of `is_prompt` (which controls MCP prompt exposure).
  - `slug` string, nullable — Optional human-readable alias (`@type/alias`). Lowercase slug, max 60 chars, not purely numeric. Resolves to the same capsule as its numeric ref.
  - `summary` string, nullable — Short summary. A non-empty value is REQUIRED from AI/MCP callers whenever the edit changes content_md or field_values on an unencrypted capsule — resend the current one if it still fits. `null` clears the summary and is accepted only where that requirement does not apply: a metadata-only edit, an encrypted capsule, or a non-AI caller.
  - `tags` string[] — Replace the capsule's tags. Omit to leave unchanged; send `[]` to clear. Free-form; normalized to slugs and deduped server-side.
  - `title` string — New capsule title
  - `token_bindings` object — Per-token prompt bindings (`{ token: { kind: 'field'|'open', required?, description? } }`). Partial map, merged with the stored set. Web-editor only; the body remains the sole way to add or remove a token.
  - `wrapped_cek` string — Wrapped CEK; required when enabling encryption.

## Response `200`

Successful response

- object
  - `agent_meta` object, nullable
  - `alias_dropped` boolean
  - `alsoAvailableAsSkill` string
  - `archive_event_id` string, nullable
  - `archive_reason` string, nullable
  - `archived_at` string, nullable
  - `attachments` object[]
  - `capsule_keys` object[]
  - `categories` object[]
    - `name` string, required
    - `slug` string, required
  - `code_excerpt` string, nullable
  - `content` object
    - `bindings` object
    - `fields` object
    - `format` 'markdown' | 'composed' | 'structured' | 'log', required
    - `source` string
    - `summary` string, nullable
    - `text` string
  - `content_excerpt` string, nullable
  - `content_md` string, nullable
  - `content_rendered` string, nullable
  - `cover` object, nullable
  - `created_at` string
  - `created_by` string
  - `deleted_at` string, nullable
  - `draftAttachmentsMap` object
  - `evicted_version_nums` integer[]
  - `field_values` object
  - `flag_reason` string, nullable
  - `flagged_at` string, nullable
  - `id` string, required — UUID v4 string
  - `inbound_ref_count` integer
  - `incomplete` boolean
  - `is_agent` boolean
  - `is_encrypted` boolean
  - `is_prompt` boolean
  - `is_stale` boolean
  - `language` string, nullable
  - `last_entry_at` string, nullable
  - `last_fetched_at` string, nullable
  - `log` object
    - `append_via` string, required
    - `bound_type` object, required
      - `id` string, required — UUID v4 string
      - `name` string, required
      - `slug` string, required
    - `owned_log_ref` string, nullable, required
    - `role` 'owner' | 'log', required
  - `log_entries` object[]
  - `log_entries_next_cursor` string, nullable
  - `log_entries_total` integer
  - `log_entry_order` string
  - `log_field_schema` object[]
  - `log_period_key` string, nullable
  - `log_period_next` string, nullable
  - `log_period_prev` string, nullable
  - `missing_required_fields` string[]
  - `owned_log` object, nullable
  - `owner_capsule` object, nullable
  - `owner_capsule_id` string, nullable
  - `owner_log_binding` boolean
  - `owner_log_type` object, nullable
  - `preview_fields` object[]
  - `project_color` string, nullable
  - `project_id` string, nullable
  - `project_name` string, nullable
  - `project_slug` string, nullable
  - `prompt_meta` object, nullable
  - `prompt_name` string, nullable
  - `ref_id` integer
  - `resolvedCrossRefs` object
  - `rollover` string, nullable
  - `share_display` 'article' | 'prompt' | 'showcase', nullable
  - `share_display_effective` 'article' | 'prompt' | 'showcase', nullable
  - `skill_republish_needed` boolean
  - `slug` string, nullable
  - `summary` string, nullable
  - `summary_stale` boolean
  - `summary_updated_at` string, nullable
  - `tags` object[]
    - `name` string, required
    - `slug` string, required
  - `tags_dropped` boolean
  - `tags_truncated` boolean
  - `title` string
  - `token_bindings` object
  - `type_color` string, nullable
  - `type_content_md_max` integer, nullable
  - `type_guidance` string, nullable
  - `type_icon` string, nullable
  - `type_id` string — UUID v4 string
  - `type_log_entry_order` string, nullable
  - `type_log_target_type_id` string, nullable
  - `type_name` string
  - `type_rollover` string, nullable
  - `type_share_template` string, nullable
  - `type_slug` string
  - `type_structure` string, nullable
  - `unreferenced` boolean
  - `updated_at` string
  - `version_skip_reason` string, nullable
  - `version_skipped` boolean
  - `warnings` string[]
  - `workspace_id` string, nullable

## Changes

> 6 revisions in range; 3 could not be searched.

- **2026-08-29** `9ca3e15b9d44` — 3 info
  - added the new optional request property `incomplete`
  - added the optional property `incomplete` to the response with the `200` status
  - added the optional property `missing_required_fields` to the response with the `200` status

[Change history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/capsules/:id/put.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-service-production.skmtc.workers.dev/v1/apis/symbol/symbol-api/revisions/9ca3e15b9d44/schema)