> ## 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.

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)