---
title: "Import external documents into a collection"
method: POST
path: "/v1/collections/{collection_identifier}/import"
tags: ["Collections"]
---

# Import external documents into a collection

`POST /v1/collections/{collection_identifier}/import`

Reconstruct documents (with vectors + lineage) from one external export using a validated mapping, and write them into the collection via the BYO write core. Use /import/infer and /import/validate-mapping first; dry_run reconstructs and validates without writing.

## Path parameters

- `collection_identifier` string, required — The ID or name of the collection to import into

## Request body

- ImportRequest — Request body for POST /v1/collections/{collection_id}/import.
  - `export` object — One export object (e.g. an asset with its scene arrays).
  - `mapping` ImportMapping, required — The finalized mapping. This IS the import config.
    - `fields` FieldMapping[]
      - `source_field` string, required
      - `target` MappingTarget, required — Where a source field lands in the Mixpeek document.
        - `kind` 'metadata' | 'vector' | 'identity' | 'parent' | 'ignore', required — metadata | vector | identity | parent | ignore
        - `path` string, nullable — Target path for kind=metadata (e.g. 'metadata.brand').
        - `index` string, nullable — Vector index name for kind=vector.
        - `dim` integer, nullable — Vector dimension for kind=vector.
        - `dtype` string, nullable — Source vector dtype for kind=vector (e.g. 'float16-base64').
        - `role` 'root_object_id' | 'root_bucket_id' | 'source_object_id' | 'source_document_id' | 'source_collection_id' | 'document_id' | 'content_hash', nullable — Lineage role for kind=identity.
        - `chain_position` integer, nullable — Position in chain[] for kind=parent.
        - `expected_type` 'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'vector' | 'object' | 'null', nullable — The source type this target requires. When set and the inferred source type differs, validate_mapping flags it (unhappy case f).
    - `source_type` 'bucket' | 'collection', nullable
    - `chain_template` object, nullable
  - `explode` ExplodeSpec — The document-explosion inputs the flat mapping does not carry.
    - `explode_axis` string, required — Export path of the doc-generating array (e.g. 'scene_content').
    - `vector_join` VectorJoin — How a separate vector array aligns to the exploded elements.
      - `array` string, required — Export path of the vector array (e.g. 'embeddings').
      - `key` string, required — Field both the element and the vector row share (e.g. 'scene_index').
      - `index` string, required — Target vector index name to store the decoded vector under.
      - `vector_field` string — Field on the vector row holding the encoded vector.
  - `dry_run` boolean — Reconstruct and validate only; write nothing.
  - `seed_ledger` boolean — Seed the ledger for heal-skip (BACKE-3367; no-op until available).

## Response `200`

Successful Response

- ImportResponse — Result of a collection import.
  - `imported` integer — Documents written (0 on dry_run).
  - `reconstructed` integer — Documents reconstructed from the export.
  - `skipped` integer — Rows that failed reconstruction.
  - `dry_run` boolean
  - `errors` ImportRowError[]
    - `row` integer, required — Index of the exploded element that failed (-1 = whole-export).
    - `error` string, required
  - `warnings` string[]

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/1c7f31821424/schema)