> ## 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](https://docs.mixpeek.com/docs/vector-store/documents.md#upsert-documents), so imported documents arrive
with their vectors and their [lineage](https://docs.mixpeek.com/docs/vector-store/documents.md#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.

Three calls. The first two write nothing.

**1. 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.

**2. 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.

**3. 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`.

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

> [!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.

## 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](https://docs.mixpeek.com/docs/vector-store/documents.md) for the single-call BYO upsert
* [Collection Lifecycle](https://docs.mixpeek.com/docs/vector-store/collection-lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.