---
title: "Create a capsule"
method: POST
path: "/api/preview/capsules"
tags: ["capsule"]
---

# Create a capsule

`POST /api/preview/capsules`

## Request body

- object
  - `agent` boolean — Package this capsule as a Claude Code agent. Omit to inherit the Type's packaging default; set explicitly to override. Encrypted capsules can't be agents.
  - `agent_meta` object, nullable — First-class agent authoring metadata (subagent name, description, and per-key frontmatter overrides). Omit for none. Overrides the capsule's slug/summary/field_values fallbacks when packaged as an agent.
    - `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[] — Category slugs from the curated taxonomy (max 10). Unknown slugs are rejected with a 400 naming the offending value. Fetch valid slugs from `GET /api/preview/categories`.
  - `cek_params` object — Opaque CEK metadata produced by the client crypto layer
  - `content_md` string — Markdown body. Empty string for no content. Maximum length is configured per-Type via `content_md_max` (default 20000, ceiling 90000).
  - `draftAttachmentIds` string[] — Draft attachment ids to associate on create.
  - `draftId` string — Draft attachment session id; required when draftAttachmentIds is present.
  - `field_values` object — Structured field values keyed by field name. Validated against the Type's `field_schema` at write time; undeclared keys are rejected.
  - `is_encrypted` boolean
  - `is_prompt` boolean — Expose this capsule on the MCP `prompts` surface. Omit to inherit the Type's default; set explicitly to override. Toggling it does not move the capsule or change its `@type/ref`.
  - `project_id` string, nullable — UUID v4 string
  - `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 — Optional short summary (LLM-generated or hand-written).
  - `tags` string[] — Free-form tags (max 20). Each is normalized to a slug and deduped server-side (e.g. `Foo Bar` and `foo-bar` collapse to one). Purely numeric or empty-after-normalization values are dropped.
  - `title` string, required — Human-readable capsule title
  - `type_id` string — Target Type. Omit to fall back to the user's default Type for the workspace.
  - `workspace_id` string, nullable — Workspace context. Accepts: "personal" for your personal workspace, an organization workspace name (full or partial — e.g. "Verdant Studio" or "Verdant"), or a workspace UUID. The MCP server resolves names against the user's accessible workspaces; ambiguous or unknown names return an error listing available workspaces — call list_workspaces in that case. Omit to use the default: personal for personal API keys, the bound organization for organization API keys.
  - `wrapped_cek` string — Wrapped per-capsule content-encryption key (E2EE)

## Response `201`

Successful response

- object
  - `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
  - `form_answered_at` string, nullable
  - `form_responses` object, nullable
  - `form_schema` object, nullable
    - `sections` object[], required
      - `optional` boolean — True for a bonus section: its questions never gate `form_answered_at` and are revealed via "Answer more".
      - `questions` object[], required
        - `field` object, required — The FieldDefinition validating this question's answer — its `name` keys the response in `form_responses`.
          - `columns` object[] — For a `table` field: the ordered column sub-schema. Each column is a scalar field (text/number/date/datetime/enum/boolean) with its own name, optional `required` flag, and applicable rules. Required (non-empty) iff type is `table`; invalid on any other type.
            - `enum_values` string[] — Closed value list — required (and non-empty) iff the column type is `enum`.
            - `name` string, required — Field identifier — also the `{{field_name}}` interpolation token.
            - `required` boolean — When true, every row must provide a value for this column.
            - `required_message` string — Custom error message returned when a required column cell is missing.
            - `rules` union[] — Type-appropriate validation rules for this column's scalar value.
              - …
            - `type` 'text' | 'number' | 'date' | 'datetime' | 'enum' | 'boolean', required — Scalar value type for this column.
          - `enum_values` string[] — Closed value list — required (and non-empty) iff type is `enum` or `multi_enum`.
          - `item_rules` union[] — For a `list` field: text rules applied to EVERY item (e.g. a single min/max length that governs all items). Only valid when type is `list`.
            - union
              - …
          - `name` string, required — Field identifier — also the `{{field_name}}` interpolation token.
          - `reference_type_slug` string — Optional Type slug constraining a `reference`/`multi_reference` field's target. Only valid on a `reference` or `multi_reference` field.
          - `required` boolean — When true, a capsule must provide a value for this field.
          - `required_message` string — Custom error message returned when a `required` field is missing. Applies only to the presence check; per-rule messages live on each rule.
          - `rules` union[] — Type-appropriate validation rules.
            - union
              - …
          - `type` 'text' | 'paragraph' | 'number' | 'datetime' | 'date' | 'boolean' | 'enum' | 'multi_enum' | 'reference' | 'multi_reference' | 'list' | 'table' | 'image', required — Field value type.
        - `prompt` string, required — The question shown to the human. Policy-capped at 20 words.
      - `title` string, required — Section (tab) label, e.g. "Absolutely needed".
    - `success_note` string — Optional celebration copy shown on submit; code-level default copy is the fallback. Policy-capped at 30 words.
    - `version` 1, required
  - `id` string, required — UUID v4 string
  - `inbound_ref_count` integer
  - `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
  - `owned_log` object, nullable
  - `owner_capsule` object, nullable
  - `owner_capsule_id` string, nullable
  - `owner_log_binding` boolean
  - `owner_log_type` object, nullable
  - `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
  - `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_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

---

[API](https://skmtc.net/symbol/apis/symbol-api.md) · [All operations](https://skmtc.net/symbol/apis/symbol-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/symbol/symbol-api/revisions/c690ac22ae04/schema)