---
title: "Stage a complete selected Symbol export for one human review; unprotected selections use ordinary import"
method: POST
path: "/api/preview/import/runs"
tags: ["import"]
---

# Stage a complete selected Symbol export for one human review; unprotected selections use ordinary import

`POST /api/preview/import/runs`

## 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/runs`
- 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`

## Query parameters

- `ws` string: Optional workspace context for the request. Same value rules as the MCP `workspace` tool argument. Omit to use the caller's default workspace.

## Request body

- object
  - `configuration` object, required
    - `confirm_exposure` boolean
    - `mark_incomplete` boolean
    - `sources` object[], required
      - `create_type` object
        - `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.
              - …
            - `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
              - …
          - `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
              - …
          - `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
      - `source_type_slug` string, required
      - `target_type_id` string: UUID v4 string
  - `descriptors` object[], required
    - `bytes` integer, required
    - `index` integer, required
    - `sha256` string, required
    - `source_type_slug` string, required
  - `item_count` integer, required
  - `workspace_id` string, nullable: UUID v4 string

## Response `200`

No protected destination: requires_review is false, no upload was created. Use ordinary import.

- object
  - `requires_review` boolean
  - `run` object
    - `expected_chunks` integer
    - `expires_at` string, date-time
    - `finalized` object, nullable
    - `id` string, required: UUID v4 string
    - `revision` integer, required
    - `selection_digest` string, required
    - `uploaded_indexes` integer[]

## Other responses

- `201`: Successful response

## Changes

- **2026-11-08** `fd7b0a7085e4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/symbol-chat/apis/symbol-api/changes/api/preview/import/runs/post.md)

---

[API](https://skmtc.dev/symbol-chat/apis/symbol-api.md) - [All operations](https://skmtc.dev/symbol-chat/apis/symbol-api/llms.txt) - [OpenAPI document](https://skmtc.dev/symbol-chat/apis/symbol-api/revisions/3ae8310b31e1?raw)