---
title: "Create a type"
method: POST
path: "/api/preview/types"
tags: ["type"]
---

# Create a type

`POST /api/preview/types`

## Request body

- object
  - `ai_settings_policy` object — Which classes of this Type's settings an AI (MCP) caller may change. Omit to accept the origin default. Human-controlled only — an AI caller that sends this is rejected.
    - `allow_all` boolean, required — When true, AI may change any setting class of this Type (except the permanently human-only settings: encryption and this policy itself).
    - `allowed_classes` string[], required — When allow_all is false, the setting classes AI may change. An empty array means AI may change no settings. Ignored when allow_all is true.
  - `color` 'violet' | 'sage' | 'ocean' | 'amber' | 'rose' | 'slate' | 'teal' | 'plum' — Tint-token color key for this Type's icon, from the closed palette. Omit for a color derived deterministically from the slug.
  - `content_md_max` integer — Maximum `content_md` length (UTF-16 code units) for capsules of this Type. Floor 0 disables bodies (title-only Type); ceiling 90000. Defaults to 20000 when omitted.
  - `default_project_id` string, nullable — UUID v4 string
  - `expire_after_days` integer — Archive capsules of this Type after N days. Must exceed stale_after_days.
  - `field_body_template` string — Deprecated alias for `output_template`, accepted for backward compatibility. Prefer `output_template`; if both are sent, `output_template` wins.
  - `field_content_max` integer — Maximum SUMMED length (UTF-16 code units) of one write's `field_values` — a single capsule's field values, or a single log entry's. The fields-side companion to `content_md_max`; for a `log` Type (and any Type with `content_md_max: 0`) it is the only content cap that applies. Floor 0 forbids field content; ceiling 90000. Defaults to 90000 when omitted (no change from today). Part of the 'Limits / guardrails' class — editable by an AI/MCP caller only when a person grants that class.
  - `field_count_max` integer — Maximum number of typed fields this Type's `field_schema` may declare — a guardrail bounding schema size (never capsule content), in the 'Limits / guardrails' class for AI-permission purposes. Floor 0 forbids fields; ceiling 50 (the global limit). Defaults to 50 when omitted.
  - `field_count_min` integer — Minimum number of fields a freeform capsule must provide (pairs with field_count_max). Floor 0 (no minimum); ceiling 50. Must not exceed field_count_max. Defaults to 0.
  - `field_mode` 'structured' | 'freeform' — Field-authoring mode: `structured` (named fields via `field_schema`, the default) or `freeform` (per-type policies via `freeform_schema`, AI names/counts fields). Freeform requires `structure: standard`.
  - `field_schema` object[] — Ordered list of typed-field definitions for capsules of this Type. Omit (or `[]`) for a pure-prose Type. Each field has a name, type, optional `required` flag + `required_message`, and type-appropriate validation `rules`. Structured mode only — ignored in freeform mode.
    - `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.
        - union
          - object — Length/word-count bound for a `text` field.
            - `kind` 'min_length' | 'max_length' | 'min_words' | 'max_words', required
            - `message` string — Custom error message returned when this rule fails.
            - `value` integer, required — Numeric operand for a bound/length rule.
          - object — Numeric bound for a `number` field.
            - `kind` 'min' | 'max', required
            - `message` string — Custom error message returned when this rule fails.
            - `value` number, required — Numeric operand for a bound/length rule.
          - object — Predefined format check (url|email|slug) for a `text` field.
            - `format` 'url' | 'email' | 'slug', required
            - `kind` 'format', required
            - `message` string — Custom error message returned when this rule fails.
          - object — Substrings that must NOT appear in a text value.
            - `kind` 'forbidden', required
            - `message` string — Custom error message returned when this rule fails.
            - `substrings` string[], required
          - object — Item/row-count bound for a collection field (`list`/`multi_*`/`table`).
            - `kind` 'min_items' | 'max_items', required
            - `message` string — Custom error message returned when this rule fails.
            - `value` integer, required — Numeric operand for a bound/length rule.
          - object — Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct.
            - `kind` 'unique_items', required
            - `message` string — Custom error message returned when this rule fails.
      - `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
        - object — Length/word-count bound for a `text` field.
          - `kind` 'min_length' | 'max_length' | 'min_words' | 'max_words', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Numeric bound for a `number` field.
          - `kind` 'min' | 'max', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` number, required — Numeric operand for a bound/length rule.
        - object — Predefined format check (url|email|slug) for a `text` field.
          - `format` 'url' | 'email' | 'slug', required
          - `kind` 'format', required
          - `message` string — Custom error message returned when this rule fails.
        - object — Substrings that must NOT appear in a text value.
          - `kind` 'forbidden', required
          - `message` string — Custom error message returned when this rule fails.
          - `substrings` string[], required
        - object — Item/row-count bound for a collection field (`list`/`multi_*`/`table`).
          - `kind` 'min_items' | 'max_items', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct.
          - `kind` 'unique_items', required
          - `message` string — Custom error message returned when this rule fails.
    - `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
        - object — Length/word-count bound for a `text` field.
          - `kind` 'min_length' | 'max_length' | 'min_words' | 'max_words', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Numeric bound for a `number` field.
          - `kind` 'min' | 'max', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` number, required — Numeric operand for a bound/length rule.
        - object — Predefined format check (url|email|slug) for a `text` field.
          - `format` 'url' | 'email' | 'slug', required
          - `kind` 'format', required
          - `message` string — Custom error message returned when this rule fails.
        - object — Substrings that must NOT appear in a text value.
          - `kind` 'forbidden', required
          - `message` string — Custom error message returned when this rule fails.
          - `substrings` string[], required
        - object — Item/row-count bound for a collection field (`list`/`multi_*`/`table`).
          - `kind` 'min_items' | 'max_items', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct.
          - `kind` 'unique_items', required
          - `message` string — Custom error message returned when this rule fails.
    - `type` 'text' | 'paragraph' | 'number' | 'datetime' | 'date' | 'boolean' | 'enum' | 'multi_enum' | 'reference' | 'multi_reference' | 'list' | 'table' | 'image', required — Field value type.
  - `format` 'markdown' — Content format the package emits. `markdown` is the only supported value; it is determined by the package and shown locked in the UI.
  - `freeform_schema` object[] — Per-field-type policies for a `freeform` Type — each { type, rules?, item_rules? } declares an allowed field type and its shared caps (e.g. text max_words, list max_items). Required and non-empty when `field_mode` is `freeform`; must be omitted/empty otherwise.
    - `item_rules` union[] — For a `list` policy: text rules applied to EVERY item of every list (e.g. a shared per-item max length). Only valid on a `list` policy.
      - union
        - object — Length/word-count bound for a `text` field.
          - `kind` 'min_length' | 'max_length' | 'min_words' | 'max_words', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Numeric bound for a `number` field.
          - `kind` 'min' | 'max', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` number, required — Numeric operand for a bound/length rule.
        - object — Predefined format check (url|email|slug) for a `text` field.
          - `format` 'url' | 'email' | 'slug', required
          - `kind` 'format', required
          - `message` string — Custom error message returned when this rule fails.
        - object — Substrings that must NOT appear in a text value.
          - `kind` 'forbidden', required
          - `message` string — Custom error message returned when this rule fails.
          - `substrings` string[], required
        - object — Item/row-count bound for a collection field (`list`/`multi_*`/`table`).
          - `kind` 'min_items' | 'max_items', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct.
          - `kind` 'unique_items', required
          - `message` string — Custom error message returned when this rule fails.
    - `rules` union[] — Caps applied to EVERY field of this type (e.g. `max_words` for text, `max_items` for list). Shared per-type — there are no per-field rules in freeform mode.
      - union
        - object — Length/word-count bound for a `text` field.
          - `kind` 'min_length' | 'max_length' | 'min_words' | 'max_words', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Numeric bound for a `number` field.
          - `kind` 'min' | 'max', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` number, required — Numeric operand for a bound/length rule.
        - object — Predefined format check (url|email|slug) for a `text` field.
          - `format` 'url' | 'email' | 'slug', required
          - `kind` 'format', required
          - `message` string — Custom error message returned when this rule fails.
        - object — Substrings that must NOT appear in a text value.
          - `kind` 'forbidden', required
          - `message` string — Custom error message returned when this rule fails.
          - `substrings` string[], required
        - object — Item/row-count bound for a collection field (`list`/`multi_*`/`table`).
          - `kind` 'min_items' | 'max_items', required
          - `message` string — Custom error message returned when this rule fails.
          - `value` integer, required — Numeric operand for a bound/length rule.
        - object — Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct.
          - `kind` 'unique_items', required
          - `message` string — Custom error message returned when this rule fails.
    - `type` 'text' | 'paragraph' | 'list', required — A field type the AI/MCP caller may use in this Type.
  - `guidance` string — Type-level guidance markdown shown to AI assistants when creating or interpreting capsules of this Type.
  - `guidance_max` integer — Maximum `guidance` length (UTF-16 code units) for this Type. Floor 0 means the Type carries no guidance; ceiling 5000. Defaults to 5000 when omitted (no change from today). Part of the 'Limits / guardrails' class — editable by an AI/MCP caller only when a person grants that class in the Type's AI permissions.
  - `hide_orphan_warning` boolean — Suppress the orphan-capsules banner on this Type's detail page. When omitted or `false`, the banner is shown whenever the Type contains capsules with zero inbound references.
  - `icon` 'building' | 'tower' | 'briefcase' | 'landmark' | 'store' | 'users' | 'rocket' | 'box' | 'layers' | 'globe' | 'sparkles' | 'code' | 'book' | 'file-text' | 'notebook' | 'lightbulb' | 'flask' | 'palette' | 'music' | 'camera' | 'image' | 'map-pin' | 'calendar' | 'clipboard' | 'message' | 'heart' | 'star' | 'flag' | 'tag' | 'bookmark' | 'graduation' | 'leaf' | 'compass' | 'puzzle' | 'target' | 'wand' — Icon glyph key for this Type's visual identity, from the closed icon library. Capsules of the Type render it. Omit for a monogram default.
  - `is_encrypted` boolean — Enable end-to-end encryption for capsules of this Type. One-way: cannot be reverted.
  - `log_entry_order` 'newest_first' | 'oldest_first' — Default order a `log`-structure Type's entry stream renders in: `newest_first` (default) or `oldest_first`. The Stream sort toggle seeds from this. Meaningful only when `structure = 'log'`.
  - `log_mode` 'period' | 'owned' — Which shape a `log`-structure Type's capsules take — the two are exclusive. `period` (default): capsules are dated buckets and appends name the Type. `owned`: capsules are the dedicated logs of capsules in other Types, appends must name the owner capsule, and `rollover`/`log_timezone` are inert. Meaningful only when `structure = 'log'`.
  - `log_target_type_id` string, nullable — UUID v4 string
  - `log_timezone` string — IANA timezone name in which this log Type's daily/weekly/monthly rollover boundary is computed (e.g. "America/New_York"). Default "UTC".
  - `name` string, required — Human-readable Type name (e.g. "Recipes", "Snippets").
  - `output_template` string — Optional output template for a field-structured Type. When set, a capsule's `field_values` are composed through it into rendered content at read time — `{{field_name}}` tokens substitute declared field values. Empty means the content is the fields shown as-is (structured content).
  - `package_as` 'standard' | 'skill' | 'agent' — Default packaging for NEW capsules of this Type. `standard` (default), `skill` (new capsules seeded as skills, eligible to publish), or `agent` (new capsules seeded as Claude Code subagent definitions, syncable to project files, `--agents` JSON, or a plugin). A default only — never retroactive; each capsule's packaging is individually overridable.
  - `paragraph_rendering` 'plain' | 'markdown' — How this Type's capsules render standalone `paragraph` field values in the read view: `plain` (default) shows literal text; `markdown` renders them through the sanitized Markdown pipeline. Governs standalone field display only — values interpolated into an `output_template` body already render as Markdown and are unaffected.
  - `prompt_default` boolean — When true, capsules created under this Type default their per-capsule prompt facet on (exposed on the MCP `prompts` surface). Applies to NEW capsules only — never retroactively changes existing capsules.
  - `rollover` 'daily' | 'weekly' | 'monthly' | 'manual' — Rollover policy for a `log`-structure Type: `daily` (default), `weekly`, `monthly`, or `manual`. Governs how appended entries bucket into period capsules. Meaningful only when `structure = 'log'`.
  - `share_template` 'article' | 'prompt' | 'showcase' — How this Type's capsules render on a public share page. `article` (default) is the reading layout; `prompt` is the grab-and-use template.
  - `slug` string, required — URL-safe lowercase slug
  - `slug_source` string, nullable — Name of a declared `text` field whose value derives each capsule's alias — the value is normalized (trimmed + lowercased) to the canonical alias, so the retrieval alias can never diverge from the external ID the field holds. Omit or `null` for no derivation. Structured, non-encrypted, non-log Types only.
  - `stale_after_days` integer — Mark capsules of this Type as stale after N days.
  - `structure` 'standard' | 'log' — Capsule body shape for this Type, chosen on the cover page. `standard` (default) or `log`. Persisted only; does not change body behaviour.
  - `summary` string — Optional short summary of what the Type holds.
  - `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.

## Response `201`

Successful response

- object
  - `ai_settings_policy` object, nullable
  - `capsule_count` integer
  - `color` string, nullable
  - `content_bytes` integer, nullable
  - `content_md_max` integer, nullable
  - `created_at` string
  - `created_by` string
  - `default_project_id` string, nullable
  - `evicted_version_nums` integer[]
  - `expire_after_days` integer, nullable
  - `field_content_max` integer, nullable
  - `field_count_max` integer, nullable
  - `field_count_min` integer, nullable
  - `field_mode` string, nullable
  - `field_schema` object[], nullable
  - `form_packaged_at` string, nullable
  - `format` string, nullable
  - `freeform_schema` object[], nullable
  - `guidance` string, nullable
  - `guidance_hash` string, nullable
  - `guidance_max` integer, nullable
  - `guidance_token` string, nullable
  - `guidance_token_status` 'ok' | 'not_required' | 'unavailable'
  - `hide_orphan_warning` boolean
  - `icon` string, nullable
  - `id` string, required — UUID v4 string
  - `is_encrypted` boolean
  - `last_capsule_at` string, nullable
  - `log_addressing` object, nullable
  - `log_entry_order` string, nullable
  - `log_mode` string, nullable
  - `log_owner_types` string[], nullable
  - `log_target` object, nullable
  - `log_target_type_id` string, nullable
  - `log_timezone` string, nullable
  - `name` string
  - `output_template` string, nullable
  - `package_as` string, nullable
  - `paragraph_rendering` string, nullable
  - `prompt_default` boolean
  - `rollover` string, nullable
  - `share_template` string, nullable
  - `slug` string
  - `slug_source` string, nullable
  - `stale_after_days` integer, nullable
  - `structure` string, nullable
  - `summary` string, nullable
  - `updated_at` string
  - `version_skip_reason` string, nullable
  - `version_skipped` boolean
  - `warnings` string[]
  - `workspace_id` string, nullable
  - `workspace_name` 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)