> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Import an External Export

> Reconstruct documents with vectors and lineage from another system's export, in three calls that validate before anything is written

Import rebuilds documents from one external export and writes them into a
collection through the same BYO write core as
[upsert](/docs/vector-store/documents#upsert-documents), so imported documents arrive
with their vectors and their [lineage](/docs/vector-store/documents#carry-lineage-on-the-way-in)
intact.

<Note>
  **The target can be a collection that has a feature extractor.** Import goes
  through the BYO write core and submits no extraction batch, so the vectors in
  your export are the vectors that get stored. Nothing re-embeds them on the way
  in, and bucket and object lineage on the imported rows is preserved.

  This says nothing about later runs. A trigger or a batch you start afterwards
  treats these documents like any others.
</Note>

Three calls. The first two write nothing.

<Steps>
  <Step title="Infer a mapping from a sample">
    `POST /v1/collections/import/infer` reads a sample of your export and
    returns the source fields it found with a suggested source-to-target
    mapping.

    ```bash theme={null}
    curl -X POST "$MP_API_URL/v1/collections/import/infer" \
      -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
      -H "Content-Type: application/json" \
      -d '{ "sample_rows": [ { "id": "a1", "title": "...", "embedding": [0.1, 0.2] } ],
            "sample_size": 100 }'
    ```

    Returns `fields` and `warnings`. It runs on the sample alone, so nothing is
    written and nothing is reserved.
  </Step>

  <Step title="Validate the finished mapping">
    `POST /v1/collections/import/validate-mapping` checks the mapping you
    settled on. `mapping` is required.

    ```bash theme={null}
    curl -X POST "$MP_API_URL/v1/collections/import/validate-mapping" \
      -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
      -H "Content-Type: application/json" \
      -d '{ "mapping": { "fields": [...], "source_type": "collection" } }'
    ```

    Returns `ok` plus `errors`. It flags four things: a missing root-identity
    mapping, source and target types that disagree, a vector dimension that does
    not match a known index, and source fields it does not recognise.
  </Step>

  <Step title="Import">
    `POST /v1/collections/{collection_identifier}/import` reconstructs the
    documents and writes them. `mapping` is required.

    ```bash theme={null}
    curl -X POST "$MP_API_URL/v1/collections/$COLLECTION_ID/import" \
      -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
      -H "Content-Type: application/json" \
      -d '{ "export": { ... }, "mapping": { ... }, "dry_run": true }'
    ```

    Returns `reconstructed`, `imported`, `skipped`, `errors`, `warnings` and
    `dry_run`.
  </Step>
</Steps>

## Reading the result

| Field | Meaning |
| - | - |
| `reconstructed` | Documents rebuilt from the export. |
| `imported` | Documents written. Always `0` when `dry_run` is true. |
| `skipped` | Rows that failed reconstruction. |
| `errors` | Per-row failures. |
| `warnings` | Non-fatal notes. |

<Note>
  **A bad row does not stop the batch.** `skipped` counts rows that failed
  reconstruction while `imported` counts the ones that were written, so a
  partially-bad export gives you both, not an all-or-nothing outcome.

  Compare `reconstructed` against `imported` and `skipped` rather than checking
  for an error status. A response with `errors` in it can still have written
  most of the batch.
</Note>

<Tip>
  Run the third call with `"dry_run": true` first. It reconstructs and validates
  the full export, not a sample, and writes nothing — `imported` comes back `0`
  while `reconstructed` and `skipped` tell you what the real run would do.

  Step 2 validates the mapping. A dry run validates the mapping against every
  row of the actual export, which is a different and stronger check.
</Tip>

## Options

| Field | Default | Meaning |
| - | - | - |
| `export` | — | The export payload to import. |
| `mapping` | *required* | `fields`, plus optional `source_type` (`bucket` or `collection`) and `chain_template`. |
| `explode` | `null` | Split one export row into several documents. `explode_axis` names the doc-generating array, for example `scene_content`. |
| `dry_run` | `false` | Reconstruct and validate without writing. |
| `seed_ledger` | `false` | Seed the ledger alongside the import. |

## Related

* [Documents & Search](/docs/vector-store/documents) for the single-call BYO upsert
* [Collection Lifecycle](/docs/vector-store/collection-lifecycle)