--- title: "Import CSV, Markdown or a Symbol export as typed capsules" method: POST path: "/api/preview/import" tags: ["import"] --- # Import CSV, Markdown or a Symbol export as typed capsules `POST /api/preview/import` ## 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/import` - Auth: one of: - HTTP bearer - API key in cookie `__Secure-next-auth.session-token` - OAuth 2 - Authorization code: `https://mcp.symbol.chat/authorize` - Token URL: `https://mcp.symbol.chat/token` ## Request body - object - `create_type` object: Create this Type and import into it. Exactly one of `target_type_id` and `create_type`. - `field_schema` object[] - `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. - `precision` integer: Maximum decimal places for a `number` column. Only valid when the column type is `number`. - `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. - … - object: Numeric bound for a `number` field. - … - object: Predefined format check (url|email|slug) for a `text` field. - … - object: Substrings that must NOT appear in a text value. - … - object: Item/row-count bound for a collection field (`list`/`multi_*`/`table`). - … - object: Require every item of a `list`/`multi_enum`/`multi_reference` field to be distinct. - … - `type` 'text' | 'number' | 'date' | 'datetime' | 'enum' | 'boolean', required: Scalar value type for this column. - `unit` string: Unit label for a `number` column (e.g. "USD", "kg"). Only valid when the column type is `number`. - `derived` object: Derive this `number` field's value from a `table` column (issue #1703): a bounded aggregate (sum|avg|min|max|count). Only valid on a `number` field; the value is computed at read time, never stored, and rejected if supplied on a write. A derived field must not be `required` and must not declare its own `rules`/`unit`/`precision` — it inherits the source column's unit and precision. - `column` string, required: Name of the column within `source` to aggregate. - `op` 'sum' | 'avg' | 'min' | 'max' | 'count', required: Aggregate to apply: sum | avg | min | max over a number column, or count of rows. - `source` string, required: Name of the `table` field on this Type whose rows this value aggregates. - `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. - `precision` integer: Maximum decimal places for a `number` field's values. Only valid on a `number` field. - `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' | 'file', required: Field value type. - `unit` string: Unit label for a `number` field (e.g. "USD", "kg", "%"). Only valid on a `number` field. - `guidance` string - `name` string, required - `slug` string: The new Type's slug. Required, unless `type_slugs` is sent: then it may be omitted and the map gives it; a slug that differs from the map's is refused (409 `import_slug_mismatch`). - `summary` string - `files` object[], required: The files to import, read client-side (a .zip or folder is unpacked in the browser). CSV: usually one file. Markdown: one capsule per `.md` file. Symbol export: the `symbol-manifest.json` manifest plus its `.md` files. - `content` string, required - `path` string, required - `format` 'csv' | 'markdown' | 'symbol', required - `held_references` object[]: The `held_references` the run's previous call returned, passed back unchanged. Each is filled in once its target exists. - `capsule_id` string, required: UUID v4 string - `capsule_ref` string: The capsule's address, for reporting a reference left unfilled. - `complete` boolean: The capsule was created incomplete only because this required value was held; filling its last held value completes it. - `expires_at` integer, required: Unix seconds after which the entry is no longer honoured. - `field` string, required - `sig` string, required: Server signature; the entry is ignored if altered. - `stored` union, required: What the field held when the import created the capsule (null: nothing). The value is filled in only while the field still holds exactly this, so a later edit is never overwritten. - string - number - boolean - string[] - object[] - object: Image field value: an attachment reference (`{ attachment_id, alt }`). - `alt` string: Optional alt text — the accessibility backbone; rendered as the image `alt`. - `attachment_id` string, required: Id of the capsule attachment this image field points at. - object: File field value: an attachment reference (`{ attachment_id, label }`). - `attachment_id` string, required: Id of the capsule attachment this file field points at. - `label` string: Optional display label shown on the file chip in place of the raw file name. - `targets` string[], required: The Type slugs the held value names; it is retried by a call that imports one of them. - `value` union, required - string - number - boolean - string[] - object[] - object: Image field value: an attachment reference (`{ attachment_id, alt }`). - `alt` string: Optional alt text — the accessibility backbone; rendered as the image `alt`. - `attachment_id` string, required: Id of the capsule attachment this image field points at. - object: File field value: an attachment reference (`{ attachment_id, label }`). - `attachment_id` string, required: Id of the capsule attachment this file field points at. - `label` string: Optional display label shown on the file chip in place of the raw file name. - `mapping` object[]: Column mapping. Omit to use the mapping the analyze step proposes. - `column` string, required: A CSV column header, or a frontmatter key for Markdown. - `field` string: The target field name, for role `field`. - `role` 'title' | 'body' | 'summary' | 'slug' | 'tags' | 'field' | 'ignore', required - `mark_incomplete` boolean: Import rows that are missing required field values as incomplete capsules instead of skipping them. - `source_type_slug` string: For a Symbol export carrying several Types: which of its Types this call imports. - `target_type_id` string: Import into this existing Type. - `type_slugs` object: For a Symbol export: the `type_slugs` analyze returned, passed unchanged on every call of the run (with `type_slugs_sig`). Required for an export whose manifest names several Types. - `type_slugs_sig` string: Server signature over `type_slugs`, valid for 24 hours; pass it unchanged. - `workspace_id` string, nullable: UUID v4 string ## Response `200` Successful response - object: Result of an import: the capsules created and the rows that failed. - `capsules` object[], required - `id` string, required: UUID v4 string - `ref` string, required - `row` integer, required - `created` integer, required - `failed` object[], required - `code` string, required - `error` string, required - `path` string, nullable, required - `row` integer, required - `held_references` object[], required: References still waiting for a capsule a later call of the run creates. Pass them unchanged as `held_references` on the next call; any left after the last call named capsules outside the import and stay empty. - `capsule_id` string, required: UUID v4 string - `capsule_ref` string: The capsule's address, for reporting a reference left unfilled. - `complete` boolean: The capsule was created incomplete only because this required value was held; filling its last held value completes it. - `expires_at` integer, required: Unix seconds after which the entry is no longer honoured. - `field` string, required - `sig` string, required: Server signature; the entry is ignored if altered. - `stored` union, required: What the field held when the import created the capsule (null: nothing). The value is filled in only while the field still holds exactly this, so a later edit is never overwritten. - string - number - boolean - string[] - object[] - object: Image field value: an attachment reference (`{ attachment_id, alt }`). - `alt` string: Optional alt text — the accessibility backbone; rendered as the image `alt`. - `attachment_id` string, required: Id of the capsule attachment this image field points at. - object: File field value: an attachment reference (`{ attachment_id, label }`). - `attachment_id` string, required: Id of the capsule attachment this file field points at. - `label` string: Optional display label shown on the file chip in place of the raw file name. - `targets` string[], required: The Type slugs the held value names; it is retried by a call that imports one of them. - `value` union, required - string - number - boolean - string[] - object[] - object: Image field value: an attachment reference (`{ attachment_id, alt }`). - `alt` string: Optional alt text — the accessibility backbone; rendered as the image `alt`. - `attachment_id` string, required: Id of the capsule attachment this image field points at. - object: File field value: an attachment reference (`{ attachment_id, label }`). - `attachment_id` string, required: Id of the capsule attachment this file field points at. - `label` string: Optional display label shown on the file chip in place of the raw file name. - `type` object, required - `created` boolean, required - `id` string, required: UUID v4 string - `name` string, required - `slug` string, required - `warnings` string[], required: Non-blocking notes, such as a reference between imported capsules that could not be rewritten. ## Changes - **2026-10-19** `5778844d1f9e`: 3 info - added the new optional request property `type_slugs` - added the new optional request property `type_slugs_sig` - the request property `create_type/slug` became optional - **2026-09-30** `6a95af57f0f6`: 1 info - endpoint added [Operation history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/import/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.dev/symbol/apis/symbol-api/revisions/3a2c4ebeab51?raw)