---
title: "Propose how CSV, Markdown or a Symbol export would import, without writing"
method: POST
path: "/api/preview/import/analyze"
tags: ["import"]
---

# Propose how CSV, Markdown or a Symbol export would import, without writing

`POST /api/preview/import/analyze`

## 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/analyze`
- 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
  - `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
  - `target_type_id` string: Import into this existing Type; the proposed mapping matches its fields.
  - `workspace_id` string, nullable: UUID v4 string

## Response `200`

Successful response

- object: A proposed import plan. Nothing is written.
  - `capacity` object: Present when the destination is the personal workspace and the plan limits capsules: how many of the rows sent fit.
    - `free` integer, required: Capsules the plan has room for now.
    - `limit` integer, required: The plan's personal capsule limit.
    - `will_create` integer, required: Rows of this request that fit.
    - `will_skip` integer, required: Rows of this request past the limit, which will not import.
  - `columns` object[], required
    - `inferred_kind` string, required
    - `name` string, required
    - `sample` string, nullable, required
  - `format` 'csv' | 'markdown' | 'symbol', required
  - `import_runs_remaining` integer, required: Import calls the caller has left this hour. Each call imports up to 1,000 rows; a client splitting a larger import checks this first.
  - `issues` object[], required: Rows that would fail validation against the proposed mapping and Type.
    - `message` string, required
    - `path` string, nullable, required
    - `row` integer, required
  - `manifest_types` object[]: For a Symbol export: the Types it carries and how many capsules each.
    - `count` integer, required
    - `final_slug` string: The slug this Type takes in the destination (from `type_slugs`).
    - `name` string, required
    - `slug` string, required
  - `mapping` object[], required: The proposed mapping from source columns (or frontmatter keys) to capsule parts.
    - `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
  - `proposed_type` object, nullable, required: A new Type the import would create when no target Type is given.
    - `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, required: URL-safe lowercase slug
    - `summary` string
  - `row_count` integer, required
  - `target_type` object, nullable, required
    - `id` string, required: UUID v4 string
    - `name` string, required
    - `slug` string, required
  - `type_slugs` object: For a Symbol export: the slug each of its Types takes in the destination. Pass it, with `type_slugs_sig`, unchanged on every import call of the run.
  - `type_slugs_sig` string: Server signature over `type_slugs`, valid for 24 hours; pass it unchanged.
  - `warnings` object[], required: Rows that will import, but not exactly as the file says: values their Type does not declare, kept hidden or left out, and references that point at a capsule of another Type than their field accepts, left out. At most 100.
    - `message` string, required
    - `path` string, nullable, required
    - `row` integer, required

## Changes

- **2026-10-19** `5778844d1f9e`: 5 info
  - added the optional property `capacity` to the response with the `200` status
  - added the optional property `manifest_types/items/final_slug` to the response with the `200` status
  - added the optional property `type_slugs` to the response with the `200` status
  - added the optional property `type_slugs_sig` to the response with the `200` status
  - …1 more
- **2026-09-30** `6a95af57f0f6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/import/analyze/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)