Imports

Reads rows rows from an uploaded file, maps each spreadsheet column to an ontology property, and creates a passport per row under target. Build the mapping from the file preview, then poll the returned import until its status is terminal. Requires imports:write. Accepts an optional Idempotency-Key header.

Required attributes

Lists the team's imports, latest first. Returns a paginated list. Ontology-scoped API keys cannot use this team-wide list — fetch imports by id instead. Requires imports:read.

Optional attributes

The creation window runs as a SQL WHERE rather than a scan, so pages stay exact. Filters join the cursor's scope; see pagination.

Retrieves one import by id, with live progress counters. Poll it until status is complete, complete_with_errors, or failed. Requires imports:read.

Lists an import's per-row outcomes, so you can see exactly which rows failed and why. Filter with status; passing status=failed selects both validation and infrastructure failures. The response also carries header (the column labels) and mapping for rendering rows back to their columns. Returns a paginated list. Requires imports:read.

Optional attributes

Returns the failed rows as text/csv, not JSON — the only operation in v1 that does. Requires imports:read. It is served as an attachment named {import_id}_failed_rows.csv.

The file holds both kinds of failure — rows rejected by validation and rows lost to an infrastructure error — one row each, laid out in the import's own column order, plus a trailing Errors column holding that row's failures as Property: message fragments joined by ; . You get the original cells and the reason side by side, which is the whole point: the sheet is repairable in place.

An import with no failed rows returns a header-only file — not a 404, and not an empty body. A consumer can treat "one line" as "nothing to fix" without special-casing an error status.

The byte-order mark

The file is UTF-8 with a BOM, deliberately. It exists to be opened in a spreadsheet, and Excel reads a BOM-less UTF-8 CSV as the local 8-bit codepage, mangling every non-ASCII character in it — an ontology with a °C unit or a supplier name carrying an accent comes out as mojibake for the very people the export is for.

The cost lands on programmatic consumers instead: strip the BOM before reading the first header cell, or your first column will not match by name. It is the single most common cause of a header lookup that mysteriously fails on column one only.

When to use it

If you are handling failures programmatically, use GET /v1/imports/{import}/rows instead — it returns the same rows as JSON, with no BOM and no CSV parsing in the way.

This endpoint exists because in practice the people who repair import failures work in a spreadsheet. Export the failures, fix the cells where they already live, then feed the corrections back through retry — the retry payload takes column index → corrected value, which maps directly onto the columns you just edited.

Retries an import's failed rows, optionally with inline cell corrections. Supply rows — each entry pairs a row_id with a corrected_row that maps a column index to a fixed value — and/or scope: "infra_all" to re-run every infrastructure failure without listing them. Corrections are re-validated server-side first; rows that are still invalid come back in still_invalid with their errors and are not dispatched. Requires imports:write. Accepts an optional Idempotency-Key header.

Optional attributes