SYsymbol
capsule

Update a capsule

Changed on
put/api/preview/capsules/{id}

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/{id}
  • Auth
    • HTTP bearer
    • or API key in cookie __Secure-next-auth.session-token
    • or OAuth 2
      Authorization code: https://mcp.symbol.chat/authorize
      Token URL: https://mcp.symbol.chat/token

Path parameters

idstring required

UUID v4 string

Request body

agentboolean

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.

authored_blankboolean

Required alongside content_md: "" when the Type has an output_template: confirms you want an empty authored body instead of the template. false asks for the refusal (422 empty_body_on_templated_type) now; omitting it is accepted with a warning until the API changelog's effective date, then refused.

categoriesstring[]

Replace the capsule's categories. Omit to leave unchanged; send [] to clear. Slugs from the curated taxonomy; unknown slugs 400.

cek_paramsobject

Opaque CEK metadata produced by the client crypto layer

client_updated_atstring 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_mdstring nullable

Markdown body (source of truth). Omit to leave it unchanged. Send body text to author the body. Send null to borrow the Type's output template live again (un-fork), which also resets token_bindings. Send an empty string for an empty authored body; on a Type with an output template that also needs authored_blank: true (see authored_blank). Maximum length is configured per-Type via content_md_max (default 20000, ceiling 90000).

draftAttachmentIdsstring[]

Confirmed draft uploads staged for THIS capsule (presigned with its capsuleId) to add to it with this save. A field value or a body embed may name one by its draft id or its draft object key; the save points them at the new attachment. A draft that expired or was staged for another capsule refuses the whole save with a 422.

draftIdstring

Draft session id the drafts in draftAttachmentIds were staged in. Required when draftAttachmentIds is non-empty.

field_valuesobject

Replace the capsule's structured field values. Omit to leave unchanged. Declared fields are replaced: leave one out to clear it, send {} to clear every declared field. Values the capsule keeps for fields its Type no longer declares are kept unless named; null under such a key removes it. Validated against the Type's field_schema.

incompleteboolean

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, except that a field_values write to an incomplete capsule that leaves no required field unmet completes it (the reply carries marked_complete: true), after which required fields are enforced.

is_encryptedboolean

One-way: set to true to enable E2EE on this capsule. Cannot be reverted to false.

is_promptboolean

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

UUID v4 string

prompt_argumentsobject

Describe the open {{token}} variables in the body so an assistant using this capsule as a prompt knows what to supply: { token: { description?, required? } }. Each key must be a token in the authored body that is not filled from a Type field; a field-bound token returns 400. Merged per token with the stored values; keys you omit are unchanged.

reclaim_aliasboolean

Set true with slug to reuse an alias that belonged to a deleted capsule; without it that alias returns 409. Never frees an alias another capsule still answers to. Older mentions of the alias stay unresolved; only new mentions reach this capsule.

removeAttachmentIdsstring[]

Live attachments of this capsule to remove with this save, as DELETE /attachments/{id} would: fields and log entries that use one are emptied, and its embeds are stripped from the body (never from an encrypted body). An id that is not a live attachment of this capsule refuses the whole save with a 422.

republishboolean

For a capsule published as a skill: whether editing it republishes the skill so the served content follows the edit. When omitted, an AI assistant's edit republishes and an API key's or a signed-in person's does not. Send true to republish, or false to leave the published skill stale and republish manually. The reply's republish object says whether a republish was started. 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).

slugstring nullable

Optional human-readable alias (@type/alias). Lowercase slug, max 60 chars, not purely numeric. Resolves to the same capsule as its numeric ref.

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

tagsstring[]

Replace the capsule's tags. Omit to leave unchanged; send [] to clear. Free-form; normalized to slugs and deduped server-side.

titlestring

New capsule title

token_bindingsobject

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_cekstring

Wrapped CEK; required when enabling encryption.

Response

Successful response

agent_metaobject nullable
alias_droppedboolean
alias_reclaimableboolean
alias_reclaimedboolean
alsoAvailableAsSkillstring
archive_event_idstring nullable
archive_reasonstring nullable
archived_atstring nullable
attachmentsobject[]
capsule_keysobject[]
code_excerptstring nullable
content_excerptstring nullable
content_mdstring nullable
content_renderedstring nullable
coverobject nullable
created_atstring
created_bystring
deadCrossRefsobject

Cited @type/ref tokens whose capsule was deleted, keyed like resolvedCrossRefs. Never resolved to a capsule that now holds the same number or alias.

deleted_atstring nullable
draftAttachmentsMapobject
evicted_version_numsinteger[]
field_valuesobject
flag_reasonstring nullable
flagged_atstring nullable
idstring required

UUID v4 string

inbound_ref_countinteger
incompleteboolean
is_agentboolean
is_encryptedboolean
is_promptboolean
is_sharedboolean
is_staleboolean
languagestring nullable
last_entry_atstring nullable
last_fetched_atstring nullable
log_entriesobject[]
log_entries_next_cursorstring nullable
log_entries_totalinteger
log_entry_orderstring
log_field_schemaobject[]
log_paragraph_rendering'plain' | 'markdown'
log_period_keystring nullable
log_period_nextstring nullable
log_period_prevstring nullable
marked_completeboolean
missing_required_fieldsstring[]
owned_logobject nullable

On an owner: its owned log, or null until the first append creates it or when you may not read the log (the entries are then empty too).

owner_capsuleobject nullable

On an owned log, web shape only: the capsule it belongs to, present only when you may read that capsule.

owner_capsule_idstring nullable

The owning capsule's id, when this is an owned log and you may read the owner; otherwise null. Always null in write responses.

owner_log_bindingboolean
owner_log_typeobject nullable
preview_fieldsobject[]
project_colorstring nullable
project_idstring nullable
project_namestring nullable
project_slugstring nullable
prompt_metaobject nullable
prompt_namestring nullable
ref_idinteger
resolvedCrossRefsobject
rolloverstring nullable
share_display'article' | 'prompt' | 'showcase' nullable
share_display_effective'article' | 'prompt' | 'showcase' nullable
share_display_rendered'article' | 'prompt' | 'showcase'

What the capsule's shared page renders, after the cover fallback: a Showcase with no cover image renders as article. Present on server single-capsule reads and write responses, absent where cover presence was not looked up.

share_display_unhonored'showcase_no_cover' nullable

Why share_display_rendered differs from share_display_effective: showcase_no_cover when Showcase was chosen and the capsule has no cover image, else null. Present exactly when share_display_rendered is.

skill_name_nextstring

Present with name_changed: the name the next publish would serve it under.

skill_name_servedstring

Present with name_changed: the name the skill is served under now.

skill_republish_neededboolean
skill_republish_reasonsstring[]

Why the published skill is stale: name_changed (the next publish renames it, see skill_name_served and skill_name_next) and/or content_changed (its content is behind this capsule).

slugstring nullable
summarystring nullable
summary_staleboolean
summary_updated_atstring nullable
tags_droppedboolean
tags_truncatedboolean
titlestring
token_bindingsobject
type_colorstring nullable
type_content_md_maxinteger nullable
type_guidancestring nullable
type_guidance_notestring
type_guidance_status'current' | 'delivered'
type_guidance_status_reasonstring
type_iconstring nullable
type_idstring

UUID v4 string

type_log_entry_orderstring nullable
type_log_target_type_idstring nullable
type_namestring
type_paragraph_renderingstring nullable
type_rolloverstring nullable
type_share_templatestring nullable
type_slugstring
type_structurestring nullable
unreferencedboolean
updated_atstring
version_skip_reasonstring nullable
version_skippedboolean
viewer_can_writeboolean
visibility'self' | 'link' | 'public' | 'org_view' | 'org_edit'
warningsstring[]
workspace_idstring nullable

Changes

  • 3a2c4ebeab51Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 5778844d1f9eRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status