---
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.
  - `incomplete` boolean — Create the capsule in the `incomplete` state (issue #1703): the Type's required fields need not be satisfied yet, so it can be captured before its values are known. Provided values are still validated. Complete it later with `incomplete: false`, which enforces the required fields at that point.
  - `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
  - `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 — 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
  - `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 `201` status
  - added the optional property `missing_required_fields` to the response with the `201` status

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