{"openapi":"3.1.0","info":{"title":"Import / Export API","version":"0.1.0","description":"Bulk CSV in and out. An import is a conversation, not a request: upload the file (streamed into a staging table, never held in memory), preview it, map its columns onto a target's fields, then commit. Committing queues the work and returns 202 — a large file is minutes of work — and progress arrives as events on the tenant's normal stream rather than by polling. The service owns the job lifecycle as its own journal but owns no domain state: every row it applies becomes an ordinary command to the service that owns that entity, so inventory stays the source of truth for quantities and every invariant is enforced exactly where it always was. Rows are marked complete as they land, so a retried job resumes rather than double-applying."},"paths":{"/targets":{"get":{"tags":["targets"],"operationId":"targets.list","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImportTargetEncoded"}},"examples":{"contract":{"summary":"targets.list","value":[{"id":"inventory.adjustment","label":"Stock adjustments","description":"Applies a signed delta to an existing SKU's on-hand quantity. Rejected with InsufficientStock if it would take the SKU negative.","service":"inventory-manager","fields":[{"name":"sku","label":"SKU","type":"string","required":true,"description":"The SKU to adjust. Must already exist.","aliases":["sku","code","item","item code"]},{"name":"delta","label":"Delta","type":"integer","required":true,"description":"Signed change; may not be zero.","aliases":["delta","change","adjustment","qty","quantity"]},{"name":"reason","label":"Reason","type":"enum","required":true,"description":"Why the stock moved.","options":["received","sold","damaged","recount","returned"],"aliases":["reason","type","movement"]},{"name":"locationId","label":"Location","type":"string","required":false,"description":"The `loc_…` id where the stock moved. Defaults to the tenant's own location.","aliases":["location","locationid","warehouse","site"]}]}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The entities a CSV can be imported into, each with its field descriptors (name, type, required, accepted values). This is the same definition the service validates against and the admin UI builds its column-mapping form from, so the two cannot disagree.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_list_targets","title":"Imports: List targets","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/imports":{"get":{"tags":["imports"],"operationId":"imports.list","parameters":[{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"20"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImportJobEncoded"}},"examples":{"contract":{"summary":"imports.list","value":[{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","status":"completed","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":2,"failed":1,"skipped":1},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:01:24.000Z","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]},"queuedBy":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the tenant's import jobs, newest first. `limit` defaults to 100 and is capped at 1000 (an over-cap request is clamped, not honoured); page with `offset`.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_list_jobs","title":"Imports: List jobs","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["imports"],"operationId":"imports.upload","parameters":[{"name":"target","in":"query","schema":{"$ref":"#/components/schemas/ImportTargetId"},"required":false,"example":"inventory.item"},{"name":"filename","in":"query","schema":{"type":"string","minLength":1},"required":false,"example":"opening-stock.csv"}],"security":[{"bearer":[]}],"responses":{"202":{"description":"ImportJob","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobEncoded"},"examples":{"contract":{"summary":"imports.upload","value":{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","status":"staged","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":0,"failed":0,"skipped":0},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:00:00.000Z"}}}}}},"400":{"description":"UnreadableUpload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnreadableUploadEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Upload a CSV. The body is the raw file, streamed and parsed into a staging table as it arrives — never buffered whole, so file size is bounded by disk rather than memory. Appends `import.job-created` and returns the staged job (202) with its detected headers and row count. Without `target`, the job takes the target whose fields the headers fit best; `PUT /imports/:jobId/target` changes it before the import runs. Nothing is applied to any domain service yet. 400 `UnreadableUpload` if the body is not usable as CSV. No idempotency key: a retried upload is a second staged job by design — staging is cheap, nothing is applied until `commit`, and an unwanted job is deletable.\n\nRequires `imports:write`.","x-mcp-withheld":"The CSV's raw bytes are the request body, which a JSON tool call cannot carry; an agent submits the rows as JSON with `imports_submit_rows`.","x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"},"requestBody":{"required":true,"content":{"text/csv":{"schema":{"type":"string","format":"binary"},"example":"SKU,Product name,Qty\nMUG-SPECKLE,Speckled stoneware mug,120\nBOWL-SALT-L,\"Salt-glaze serving bowl, large\",40\nPLATE-SIDE,Side plate,12.5\n"}}}}},"/imports/{jobId}":{"get":{"tags":["imports"],"operationId":"imports.get","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ImportJob","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobEncoded"},"examples":{"contract":{"summary":"imports.get","value":{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","status":"completed","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":2,"failed":1,"skipped":1},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:01:24.000Z","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]},"queuedBy":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"One import job, including its live progress counters. Progress also arrives as events on the tenant's stream — poll this only if you are not already subscribed.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_get_job","title":"Imports: Get job","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/imports/rows":{"post":{"tags":["imports"],"operationId":"imports.submit","parameters":[],"security":[{"bearer":[]}],"responses":{"202":{"description":"ImportAccepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportAcceptedEncoded"},"examples":{"contract":{"summary":"imports.submit","value":{"jobId":"imp_01a15891-0a40-7b21-9c32-4d5e6f7a8b91","rows":3}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"422":{"description":"InvalidMapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMappingEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Submit rows as JSON rather than as a file — the entry another service uses when it already holds structured data (a channel app's catalog pull, a migration from another system). `headers` are the target's field names and `rows` the cells in that order, at most 5000 per submission (page a larger set under distinct references). The rows are staged exactly as an upload's would be, the identity mapping is validated as `PUT /imports/:jobId/mapping` validates one (422 `InvalidMapping` when a header is not a field or a required field is missing), and — unless `run` is false — the job is queued at once, so the answer is the 202 a `commit` gives. Appends `import.job-created` and `import.mapped` (and `import.queued` when it runs). Idempotency key: `reference` — a second submission with the same reference is acknowledged with the job already staged and appends nothing.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitRowsEncoded"},"example":{"reference":"sync:warehouse-sheet:2026-10-20","target":"inventory.location","headers":["name","fulfillable","note"],"rows":[["Back room",true,"Behind the shopfront"],["Returns shelf",false,null]],"run":true}}},"required":true},"x-mcp-tool":{"name":"imports_submit_rows","title":"Imports: Submit rows","toolset":"imports","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/imports/{jobId}/preview":{"get":{"tags":["imports"],"operationId":"imports.preview","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"5"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ImportPreview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPreviewEncoded"},"examples":{"contract":{"summary":"imports.preview","value":{"job":{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","status":"staged","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":0,"failed":0,"skipped":0},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:00:00.000Z"},"rows":[{"rowNumber":0,"cells":["SKU","Product name","Qty"]},{"rowNumber":1,"cells":["MUG-SPECKLE","Speckled stoneware mug","120"]},{"rowNumber":2,"cells":["BOWL-SALT-L","Salt-glaze serving bowl, large","40"]},{"rowNumber":3,"cells":["PLATE-SIDE","Side plate","12.5"]}],"suggested":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]},"candidates":[{"target":"inventory.item","matched":3,"requiredMissing":[]},{"target":"inventory.adjustment","matched":2,"requiredMissing":["reason"]},{"target":"purchasing.receipt","matched":2,"requiredMissing":["poId"]},{"target":"fulfillment.order","matched":2,"requiredMissing":["reference"]},{"target":"catalog.composite","matched":2,"requiredMissing":["componentSku"]},{"target":"catalog.product","matched":2,"requiredMissing":["productKey"]},{"target":"catalog.price","matched":1,"requiredMissing":["catalogId"]},{"target":"inventory.location","matched":0,"requiredMissing":["name"]},{"target":"crm.company","matched":0,"requiredMissing":["name"]},{"target":"crm.person","matched":0,"requiredMissing":["email"]},{"target":"fulfillment.ship","matched":0,"requiredMissing":["orderId","shipmentId"]},{"target":"purchasing.po","matched":2,"requiredMissing":["reference","supplier","unitCostCents"]},{"target":"fulfillment.pick","matched":2,"requiredMissing":["orderId","shipmentId","lineId"]},{"target":"fulfillment.refund","matched":2,"requiredMissing":["reference","orderId","amountCents","lineId"]},{"target":"purchasing.supplier-payment","matched":0,"requiredMissing":["reference","currency","method","poId","amountCents"]},{"target":"fulfillment.payout","matched":0,"requiredMissing":["provider","providerPayoutId","currency","netCents","issuedAt","kind","amountCents"]},{"target":"fulfillment.historical-order","matched":2,"requiredMissing":["externalNumber","placedAt","currency","outcome","totalCents","paidCents","name","unitPriceCents"]}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The first `limit` staged rows (default 50) plus a suggested mapping, matched from the file's headers against the target's field names and aliases. The suggestion is a starting point the caller is expected to correct — it is never applied on its own.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_preview_job","title":"Imports: Preview job","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/imports/{jobId}/target":{"put":{"tags":["imports"],"operationId":"imports.retarget","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ImportJob","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobEncoded"},"examples":{"contract":{"summary":"imports.retarget","value":{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.adjustment","filename":"opening-stock.csv","status":"staged","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":0,"failed":0,"skipped":0},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:00:40.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"ImportNotReady | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ImportNotReadyEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Point a staged or mapped job at another import `target` — the file was recognised as the wrong entity, or the caller knows better. The mapping named the old target's fields, so it is dropped and the job is `staged` again; read the preview for the new target's suggested mapping. Appends `import.target-changed`. 409 `ImportNotReady` once the job is committed (queued), running or finished. Idempotent by content: asking for the target the job already has changes nothing and appends nothing.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeImportTargetEncoded"},"example":{"target":"inventory.adjustment"}}},"required":true},"x-mcp-tool":{"name":"imports_change_target","title":"Imports: Change target","toolset":"imports","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/imports/{jobId}/mapping":{"put":{"tags":["imports"],"operationId":"imports.map","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ImportJob","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobEncoded"},"examples":{"contract":{"summary":"imports.map","value":{"id":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","status":"mapped","headers":["SKU","Product name","Qty"],"progress":{"rows":4,"applied":0,"failed":0,"skipped":0},"createdAt":"2026-10-20T06:00:00.000Z","updatedAt":"2026-10-20T06:01:10.000Z","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"ImportNotReady | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ImportNotReadyEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"422":{"description":"InvalidMapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMappingEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Set which CSV column feeds which target field. Appends `import.mapped`. Rejected with 422 `InvalidMapping` if a field is unknown, two columns claim the same field, or a required field is unmapped; 409 `ImportNotReady` once the job is committed (queued), running or finished. Idempotent by content: re-mapping a staged job replaces the mapping whole, so a retry lands on the same mapping.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportMappingEncoded"},"example":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]}}},"required":true},"x-mcp-tool":{"name":"imports_map_columns","title":"Imports: Map columns","toolset":"imports","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/imports/{jobId}/commit":{"post":{"tags":["imports"],"operationId":"imports.commit","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"}],"security":[{"bearer":[]}],"responses":{"202":{"description":"ImportAccepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportAcceptedEncoded"},"examples":{"contract":{"summary":"imports.commit","value":{"jobId":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","rows":4}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"ImportNotReady | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ImportNotReadyEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"422":{"description":"InvalidMapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMappingEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Queue the import. Returns 202 with the job id; the work runs in the background under the committer's grant, applying each row as an ordinary command to the owning service. Appends `import.queued`, which freezes the job's target and mapping. Progress arrives as `import.progressed` and finishes with `import.completed` or `import.failed`. Idempotent by state: a retried commit of a queued job is acknowledged and appends nothing, and 409 `ImportNotReady` answers a running or finished one.\n\nRequires `imports:write`.","x-mcp-tool":{"name":"imports_commit_job","title":"Imports: Commit job","toolset":"imports","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/imports/{jobId}/failures":{"get":{"tags":["imports"],"operationId":"imports.failures","parameters":[{"name":"jobId","in":"path","schema":{"$ref":"#/components/schemas/ImpId"},"required":true,"example":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"100"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RowFailureEncoded"}},"examples":{"contract":{"summary":"imports.failures","value":[{"rowNumber":3,"field":"quantity","reason":"Opening quantity must be a whole number"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ImportJobNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Every row this job rejected, with the field and reason — enough to correct the file and re-upload. The `import.rows-failed` events cap how much detail they carry; this is the complete set. Appends nothing: a read of the staged rows.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_list_failures","title":"Imports: List failures","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/mappings":{"get":{"tags":["mappings"],"operationId":"mappings.list","parameters":[{"name":"target","in":"query","schema":{"$ref":"#/components/schemas/ImportTargetId"},"required":false,"example":"inventory.item"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SavedMappingEncoded"}},"examples":{"contract":{"summary":"mappings.list","value":[{"id":"map_01a15890-3e80-7c31-8d42-5e6f7a8b9ca2","name":"Opening stock sheet","target":"inventory.item","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]},"createdAt":"2026-10-20T06:02:00.000Z"}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's saved CSV column mappings (which column feeds which field), optionally narrowed to one import `target`, to reuse on the next file of the same shape. Read-only.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_list_mappings","title":"Imports: List mappings","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["mappings"],"operationId":"mappings.create","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"SavedMapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedMappingEncoded"},"examples":{"contract":{"summary":"mappings.create","value":{"id":"map_01a15890-3e80-7c31-8d42-5e6f7a8b9ca2","name":"Opening stock sheet","target":"inventory.item","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]},"createdAt":"2026-10-20T06:02:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"422":{"description":"InvalidMapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMappingEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Save a column mapping for reuse on the next file of the same shape. Validated against the target exactly as `PUT /imports/:jobId/mapping` is, so a saved mapping can never be one that would be refused later. Appends `import.mapping-saved`. Idempotent by content — on (name, target): saving the same mapping again returns it and appends nothing.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveMappingEncoded"},"example":{"name":"Opening stock sheet","target":"inventory.item","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]}}}},"required":true},"x-mcp-tool":{"name":"imports_save_mapping","title":"Imports: Save mapping","toolset":"imports","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/mappings/{mappingId}":{"delete":{"tags":["mappings"],"operationId":"mappings.delete","parameters":[{"name":"mappingId","in":"path","schema":{"$ref":"#/components/schemas/MapId"},"required":true,"example":"map_01a15890-3e80-7c31-8d42-5e6f7a8b9ca2"}],"security":[{"bearer":[]}],"responses":{"204":{"description":"<No Content>"},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"MappingNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Forget a saved mapping. Imports already run are unaffected. Appends `import.mapping-deleted`. Idempotent: a retry meets 404 and appends nothing.\n\nRequires `imports:write`.","x-mcp-tool":{"name":"imports_delete_mapping","title":"Imports: Delete mapping","toolset":"imports","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/exports":{"post":{"tags":["exports"],"operationId":"exports.request","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ExportLink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportLinkEncoded"},"examples":{"contract":{"summary":"exports.request","value":{"exportId":"exp_01a15892-1b60-7d41-9e52-6f7a8b9cadb3","target":"inventory.item","download":"/exports/exp_01a15892-1b60-7d41-9e52-6f7a8b9cadb3/download?tenant=org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d&expires=1792476300000&sig=q3V8m1kQ0yJ7xR2bT5nW9cL4hF6dG8sA1pZ0eU3iK7o","expiresAt":"2026-10-20T06:05:00.000Z"}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ExportNotForApps | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ExportNotForAppsEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"ExportIdTaken | MirroredFromSource","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ExportIdTakenEncoded"},{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}]}}}},"422":{"description":"InvalidExportOptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidExportOptionsEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Ask for the tenant's rows for a target as CSV, and get back where to fetch them: a download link (`download`, a path on this service) signed by the service and good for five minutes (`expiresAt`). `from`/`to` narrow the period for the accounting targets; `catalogId` narrows `catalog.price` to one catalog's sheet. `columns` picks which of the target's columns are written (in the target's order) and `rules` keeps only the rows meeting every rule; an unknown column or a rule without its value is 422 `InvalidExportOptions`, before anything is appended. Appends `import.export-requested`, naming the target, columns, rules and the link's expiry — the one record that the export ran; its download appends nothing. The rows are read when the link is followed, from the owning services and as this caller — the link carries no more than the session that asked for it, and lives no longer than five minutes or that session's token, whichever ends first. Idempotent on `exportId`, scoped to the caller: the same caller's retry is acknowledged, appends nothing and answers the link first minted, which is dead once expired — a fresh download is a fresh `exportId`; another caller's request under that `exportId` is 409 `ExportIdTaken` and never sees the link. An organisation whose subscription has lapsed may still ask (it is read-only, not cut off from its data). An app is refused with 403 `ExportNotForApps`: the link is for a person in a browser, and an app reads the same rows through the owning services' list APIs.\n\nRequires `imports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestExportEncoded"},"example":{"exportId":"exp_01a15892-1b60-7d41-9e52-6f7a8b9cadb3","target":"inventory.item","columns":["sku","name","locationId","quantity"],"rules":[{"column":"quantity","op":"greater-than","value":"0"}]}}},"required":true},"x-mcp-withheld":"It answers a five-minute download link for a browser to follow, which an agent cannot hand a person nor stream into a chat; an agent reads the same rows with `imports_preview_export` or the owning service's list tools.","x-required-scopes":["imports:write"],"x-example-source":{"origin":"contract"}}},"/exports/{exportId}/download":{"get":{"tags":["exports"],"operationId":"exports.download","parameters":[{"name":"exportId","in":"path","schema":{"$ref":"#/components/schemas/ExpId"},"required":true,"example":"exp_01a15892-1b60-7d41-9e52-6f7a8b9cadb3"},{"name":"tenant","in":"query","schema":{"$ref":"#/components/schemas/TenantId"},"required":true,"example":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d"},{"name":"expires","in":"query","schema":{"type":"string"},"required":true,"example":"1792476300000"},{"name":"sig","in":"query","schema":{"type":"string","description":"the link's signature, as minted"},"required":true,"example":"q3V8m1kQ0yJ7xR2bT5nW9cL4hF6dG8sA1pZ0eU3iK7o"}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"string"},"examples":{"contract":{"summary":"exports.download","value":"sku,name,locationId,quantity\r\nMUG-SPECKLE,Speckled stoneware mug,loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4,116\r\nBOWL-SALT-L,\"Salt-glaze serving bowl, large\",loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4,40\r\n"}}}}},"403":{"description":"ExportLinkRefused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportLinkRefusedEncoded"}}}},"422":{"description":"InvalidExportOptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidExportOptionsEncoded"}}}}},"description":"Stream an export's rows as CSV (`text/csv`, with a `Content-Disposition` filename), following the link `POST /exports` answered with. The browser follows it without a bearer: the `sig` is an HMAC-SHA256 the service minted over `tenant`, `exportId` and `expires` under a key kept with the export, and it is verified — with the expiry — before anything is read (403 `ExportLinkRefused` for a bad signature, an unknown export or a link past its five minutes). The link is not single-use: within its five minutes it streams the rows again, as they stand. Rows are fetched in pages from the owning services, as the session that asked for the export, and written out as they arrive, so the response is never materialised in memory and the export size is unbounded. A read: appends nothing — the record that the export ran is the request's fact, appended by `POST /exports`.\n\nPublic: a capability link: the signature `POST /exports` minted is verified before anything is read","x-mcp-withheld":"A capability link `POST /exports` mints for a browser, authenticated by its signature rather than a session; an agent reads the same rows with `imports_preview_export`.","x-requires":{"kind":"public","reason":"a capability link: the signature `POST /exports` minted is verified before anything is read"},"x-example-source":{"origin":"contract"}}},"/exports/{target}/preview":{"get":{"tags":["exports"],"operationId":"exports.preview","parameters":[{"name":"target","in":"path","schema":{"$ref":"#/components/schemas/ExportTargetId"},"required":true,"example":"inventory.item"},{"name":"from","in":"query","schema":{"type":"string"},"required":false},{"name":"to","in":"query","schema":{"type":"string"},"required":false},{"name":"catalogId","in":"query","schema":{"$ref":"#/components/schemas/CatId"},"required":false},{"name":"columns","in":"query","schema":{"type":"string"},"required":false,"example":"sku,name,locationId,quantity"},{"name":"rules","in":"query","schema":{"type":"string","contentMediaType":"application/json"},"required":false,"example":"[{\"column\":\"quantity\",\"op\":\"greater-than\",\"value\":\"0\"}]"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"25"},{"name":"offset","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"ExportPreview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPreviewEncoded"},"examples":{"contract":{"summary":"exports.preview","value":{"target":"inventory.item","columns":["sku","name","locationId","quantity"],"headers":["sku","name","locationId","quantity"],"offset":0,"rows":[["MUG-SPECKLE","Speckled stoneware mug","loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4","116"],["BOWL-SALT-L","Salt-glaze serving bowl, large","loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4","40"]],"hasMore":false}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"422":{"description":"InvalidExportOptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidExportOptionsEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"A page of the rows an export with these options would write, as JSON: every column the target can write, the columns this export writes, up to `limit` matching rows of cell text starting `offset` matching rows in, and whether more match after them. Takes the same `columns`, `rules`, `from`/`to` and `catalogId` as `POST /exports`, so what the preview shows is what the file holds. A read: records no export.\n\nRequires `imports:read`.","x-mcp-tool":{"name":"imports_preview_export","title":"Imports: Preview export","toolset":"imports","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/events":{"get":{"tags":["events"],"operationId":"events.list","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"required":false,"example":"12"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"500"},{"name":"upTo","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/import.job-createdEncoded"},{"$ref":"#/components/schemas/import.target-changedEncoded"},{"$ref":"#/components/schemas/import.mappedEncoded"},{"$ref":"#/components/schemas/import.queuedEncoded"},{"$ref":"#/components/schemas/import.startedEncoded"},{"$ref":"#/components/schemas/import.progressedEncoded"},{"$ref":"#/components/schemas/import.rows-failedEncoded"},{"$ref":"#/components/schemas/import.completedEncoded"},{"$ref":"#/components/schemas/import.failedEncoded"},{"$ref":"#/components/schemas/import.cancelledEncoded"},{"$ref":"#/components/schemas/import.rows-discardedEncoded"},{"$ref":"#/components/schemas/import.mapping-savedEncoded"},{"$ref":"#/components/schemas/import.mapping-deletedEncoded"},{"$ref":"#/components/schemas/import.export-requestedEncoded"}]}},"examples":{"contract":{"summary":"events.list","value":[{"_tag":"import.job-created","eventId":"evt_01a15890-2c00-7a11-8b22-000000000012","txId":"tx_01a15890-2c00-7a11-8b22-000000000012","tenantId":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d","sequence":12,"occurredAt":"2026-10-20T06:00:00.000Z","source":"import-export","version":1,"actor":{"_tag":"user","id":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"},"correlationId":"req_01a15890-2c00-7a11-8b22-000000000012","payload":{"jobId":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","target":"inventory.item","filename":"opening-stock.csv","rows":4,"headers":["SKU","Product name","Qty"]}},{"_tag":"import.mapped","eventId":"evt_01a15890-2c00-7a11-8b22-000000000013","txId":"tx_01a15890-2c00-7a11-8b22-000000000013","tenantId":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d","sequence":13,"occurredAt":"2026-10-20T06:01:10.000Z","source":"import-export","version":1,"actor":{"_tag":"user","id":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"},"correlationId":"req_01a15890-2c00-7a11-8b22-000000000013","payload":{"jobId":"imp_01a15890-2c00-7a11-8b22-3c4d5e6f7a80","mapping":{"hasHeaderRow":true,"columns":[{"column":0,"field":"sku"},{"column":1,"field":"name"},{"column":2,"field":"quantity"}]}}}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The tenant's import journal at or after `since` (default 0), oldest first, for consumers catching up before joining the live stream. One response is a page: `limit` defaults to 500 and is capped at 5000 (an over-cap request is clamped). Pages are `sequence`-ordered and the boundary is stable — repeat with `since=<last event's sequence + 1>` until a page comes back smaller than `limit` to replay the journal exactly once. `upTo` (inclusive) ends the replay at a sequence instead of the journal's head — with `GET /events/head` it replays the journal as it stood at a moment. Appends nothing: a read of facts already journalled.\n\nRequires `imports:read`.","x-mcp-withheld":"The journal replay a consumer pages through to build its projection; agents read the projections the list and get tools serve, and the audit trail (`audit_trail`) for history.","x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}},"/events/head":{"get":{"tags":["events"],"operationId":"events.head","parameters":[{"name":"at","in":"query","schema":{"type":"string"},"required":true,"example":"2026-10-20T06:05:00.000Z"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Where a tenant's journal stood at a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalHead"},"examples":{"contract":{"summary":"events.head","value":{"at":"2026-10-20T06:05:00.000Z","sequence":13}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The journal's position at a moment: the last `sequence` the database had recorded for this tenant at `at` (absent when it held nothing yet), by the database's own clock rather than the service's. Replaying with `upTo=<sequence>` then gives the journal exactly as it stood then; a set of heads taken at one `at` is a consistent cut across journals. Appends nothing: a read of facts already journalled.\n\nRequires `imports:read`.","x-mcp-withheld":"Where a journal stood at a moment, for a consumer cutting journals to replay them as of then; agents read history through the audit trail (`audit_trail`).","x-required-scopes":["imports:read"],"x-example-source":{"origin":"contract"}}}},"components":{"schemas":{"ImportTargetId":{"type":"string","enum":["inventory.item","inventory.adjustment","purchasing.po","purchasing.receipt","purchasing.supplier-payment","fulfillment.order","fulfillment.pick","fulfillment.ship","fulfillment.refund","fulfillment.historical-order","fulfillment.payout","catalog.price","inventory.location","catalog.product","catalog.composite","crm.company","crm.person"],"description":"What a file is imported into, as `<service>.<entity>`: each names the owning service and the command a row becomes (an item, an adjustment, a PO, receipt or supplier payment, an order, pick, ship or refund, a historical order, a provider's payout, a price, a location, a product or composite, a company or person)."},"ImportFieldType":{"type":"string","enum":["string","integer","decimal","boolean","date","enum"],"description":"How a CSV cell is parsed into a target field: string, integer, decimal, boolean, date, or `enum` (one of the field's `options`)."},"TargetFieldEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"type":{"$ref":"#/components/schemas/ImportFieldType"},"required":{"type":"boolean"},"description":{"type":"string"},"options":{"type":"array","items":{"type":"string","minLength":1}},"aliases":{"type":"array","items":{"type":"string","minLength":1}}},"required":["name","label","type","required","description"],"additionalProperties":false},"ImportTargetEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ImportTargetId"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"service":{"type":"string","minLength":1},"referenceField":{"type":"string","minLength":1},"fields":{"type":"array","items":{"$ref":"#/components/schemas/TargetFieldEncoded"}}},"required":["id","label","description","service","fields"],"additionalProperties":false},"UnauthorizedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"TokenAlreadyUsedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TokenAlreadyUsed"]},"tokenId":{"type":"string"}},"required":["_tag","tokenId"],"additionalProperties":false},"RequestLogUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["RequestLogUnavailable"]},"tokenId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","tokenId","reason"],"additionalProperties":false},"TenantRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TenantRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"ScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ScopeRequired"]},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","required"],"additionalProperties":false},"PlatformAdminRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PlatformAdminRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"SubscriptionRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SubscriptionRequired"]},"status":{"type":"string"}},"required":["_tag","status"],"additionalProperties":false},"MirroredFromSourceEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MirroredFromSource"]},"source":{"type":"string"}},"required":["_tag","source"],"additionalProperties":false},"ImpId":{"type":"string","pattern":"^imp_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A imp-prefixed uuid, e.g. imp_9f8c1c2e-0000-4000-8000-000000000000"},"ImportStatus":{"type":"string","enum":["staged","mapped","queued","running","completed","failed","cancelled"],"description":"Where an import job is: `staged` (the file is uploaded), `mapped` (columns assigned), `queued` (committed, waiting for the worker), `running`, then `completed`, `failed` or `cancelled`."},"ColumnMapping":{"type":"object","properties":{"column":{"type":"integer","minimum":0},"field":{"type":"string","minLength":1}},"required":["column","field"],"additionalProperties":false},"ImportProgressEncoded":{"type":"object","properties":{"rows":{"type":"integer","minimum":0},"applied":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0}},"required":["rows","applied","failed","skipped"],"additionalProperties":false},"ImportJobEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ImpId"},"target":{"$ref":"#/components/schemas/ImportTargetId"},"filename":{"type":"string","minLength":1},"status":{"$ref":"#/components/schemas/ImportStatus"},"headers":{"type":"array","items":{"type":"string"}},"mapping":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnMapping"}},"hasHeaderRow":{"type":"boolean"}},"required":["columns"],"additionalProperties":false},"reference":{"type":"string","minLength":1},"progress":{"$ref":"#/components/schemas/ImportProgressEncoded"},"reason":{"type":"string"},"rowsDiscardedAt":{"type":"string"},"queuedBy":{"type":"string","minLength":1},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","target","filename","status","headers","progress","createdAt","updatedAt"],"additionalProperties":false},"ImportJobNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ImportJobNotFound"]},"jobId":{"type":"string"}},"required":["_tag","jobId"],"additionalProperties":false},"UnreadableUploadEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["UnreadableUpload"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"SubmitRowsEncoded":{"type":"object","properties":{"reference":{"type":"string","minLength":1,"maxLength":200},"target":{"$ref":"#/components/schemas/ImportTargetId"},"filename":{"type":"string","minLength":1},"headers":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"rows":{"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"boolean"},{"type":"null"}]}},"minItems":1,"maxItems":5000},"run":{"type":"boolean"}},"required":["reference","target","headers","rows"],"additionalProperties":false},"ImportAcceptedEncoded":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"rows":{"type":"integer","minimum":0}},"required":["jobId","rows"],"additionalProperties":false},"InvalidMappingEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["InvalidMapping"]},"reason":{"type":"string"},"field":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"PreviewRowEncoded":{"type":"object","properties":{"rowNumber":{"type":"integer","minimum":0},"cells":{"type":"array","items":{"type":"string"}}},"required":["rowNumber","cells"],"additionalProperties":false},"ImportMappingEncoded":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnMapping"}},"hasHeaderRow":{"type":"boolean"}},"required":["columns"],"additionalProperties":false},"TargetMatchEncoded":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ImportTargetId"},"matched":{"type":"integer","minimum":0},"requiredMissing":{"type":"array","items":{"type":"string"}}},"required":["target","matched","requiredMissing"],"additionalProperties":false},"ImportPreviewEncoded":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/ImportJobEncoded"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/PreviewRowEncoded"}},"suggested":{"$ref":"#/components/schemas/ImportMappingEncoded"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/TargetMatchEncoded"}}},"required":["job","rows","suggested","candidates"],"additionalProperties":false},"ChangeImportTargetEncoded":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ImportTargetId"}},"required":["target"],"additionalProperties":false},"ImportNotReadyEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ImportNotReady"]},"jobId":{"type":"string"},"status":{"$ref":"#/components/schemas/ImportStatus"},"expected":{"type":"string"}},"required":["_tag","jobId","status","expected"],"additionalProperties":false},"RowFailureEncoded":{"type":"object","properties":{"rowNumber":{"type":"integer","minimum":0},"field":{"type":"string"},"reason":{"type":"string","minLength":1},"code":{"type":"string"}},"required":["rowNumber","reason"],"additionalProperties":false},"MapId":{"type":"string","pattern":"^map_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A map-prefixed uuid, e.g. map_9f8c1c2e-0000-4000-8000-000000000000"},"SavedMappingEncoded":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MapId"},"name":{"type":"string","minLength":1},"target":{"$ref":"#/components/schemas/ImportTargetId"},"mapping":{"$ref":"#/components/schemas/ImportMappingEncoded"},"createdAt":{"type":"string"}},"required":["id","name","target","mapping","createdAt"],"additionalProperties":false},"SaveMappingEncoded":{"type":"object","properties":{"name":{"type":"string","minLength":1},"target":{"$ref":"#/components/schemas/ImportTargetId"},"mapping":{"$ref":"#/components/schemas/ImportMappingEncoded"}},"required":["name","target","mapping"],"additionalProperties":false},"MappingNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MappingNotFound"]},"mappingId":{"type":"string"}},"required":["_tag","mappingId"],"additionalProperties":false},"ExpId":{"type":"string","pattern":"^exp_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A exp-prefixed uuid, e.g. exp_9f8c1c2e-0000-4000-8000-000000000000"},"ExportTargetId":{"type":"string","enum":["inventory.item","purchasing.po","fulfillment.order","accounting.ledger","accounting.valuation","catalog.price","inventory.location","catalog.product"],"description":"What can be exported, as `<service>.<entity>`: items, POs, orders, the COGS ledger and valuation, prices, locations or products."},"CatId":{"type":"string","pattern":"^cat_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cat-prefixed uuid, e.g. cat_9f8c1c2e-0000-4000-8000-000000000000"},"ExportRuleOperator":{"type":"string","enum":["equals","not-equals","contains","not-contains","starts-with","greater-than","less-than","is-empty","is-not-empty"],"description":"How an export rule compares a column's cell with its value: `equals`, `not-equals`, `contains`, `not-contains`, `starts-with`, `greater-than`, `less-than` (numeric when both sides are numbers), `is-empty` or `is-not-empty` (no value). Case-insensitive."},"RequestExportEncoded":{"type":"object","properties":{"exportId":{"$ref":"#/components/schemas/ExpId"},"target":{"$ref":"#/components/schemas/ExportTargetId"},"from":{"type":"string"},"to":{"type":"string"},"catalogId":{"$ref":"#/components/schemas/CatId"},"columns":{"type":"array","items":{"type":"string"}},"rules":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","minLength":1},"op":{"$ref":"#/components/schemas/ExportRuleOperator"},"value":{"type":"string"}},"required":["column","op"],"additionalProperties":false}}},"required":["exportId","target"],"additionalProperties":false},"ExportLinkEncoded":{"type":"object","properties":{"exportId":{"$ref":"#/components/schemas/ExpId"},"target":{"$ref":"#/components/schemas/ExportTargetId"},"download":{"type":"string"},"expiresAt":{"type":"string"}},"required":["exportId","target","download","expiresAt"],"additionalProperties":false},"InvalidExportOptionsEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["InvalidExportOptions"]},"reason":{"type":"string"},"column":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"ExportNotForAppsEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ExportNotForApps"]},"appId":{"type":"string"}},"required":["_tag","appId"],"additionalProperties":false},"ExportIdTakenEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ExportIdTaken"]},"exportId":{"type":"string"}},"required":["_tag","exportId"],"additionalProperties":false},"TenantId":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"the organisation the export belongs to, as minted"},"ExportLinkRefusedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ExportLinkRefused"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"ExportPreviewEncoded":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ExportTargetId"},"columns":{"type":"array","items":{"type":"string"}},"headers":{"type":"array","items":{"type":"string"}},"offset":{"type":"integer","minimum":0},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"hasMore":{"type":"boolean"}},"required":["target","columns","headers","offset","rows","hasMore"],"additionalProperties":false},"EvtId":{"type":"string","pattern":"^evt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A evt-prefixed uuid, e.g. evt_9f8c1c2e-0000-4000-8000-000000000000"},"TxId":{"type":"string","pattern":"^tx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A tx-prefixed uuid, e.g. tx_9f8c1c2e-0000-4000-8000-000000000000"},"TenantId_1":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"An org-prefixed uuid, e.g. org_9f8c1c2e-0000-4000-8000-000000000000; a sandbox tenant is org_test_<uuid>"},"UsrId":{"type":"string","pattern":"^usr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A usr-prefixed uuid, e.g. usr_9f8c1c2e-0000-4000-8000-000000000000"},"AppId":{"type":"string","pattern":"^app_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A app-prefixed uuid, e.g. app_9f8c1c2e-0000-4000-8000-000000000000"},"InsId":{"type":"string","pattern":"^ins_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ins-prefixed uuid, e.g. ins_9f8c1c2e-0000-4000-8000-000000000000"},"CplId":{"type":"string","pattern":"^cpl_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cpl-prefixed uuid, e.g. cpl_9f8c1c2e-0000-4000-8000-000000000000"},"Actor":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/UsrId"},"impersonatedBy":{"type":"string","minLength":1},"viaPartner":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["app"]},"id":{"$ref":"#/components/schemas/AppId"},"installationId":{"$ref":"#/components/schemas/InsId"}},"required":["_tag","id","installationId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["customer"]},"id":{"$ref":"#/components/schemas/CplId"}},"required":["_tag","id"],"additionalProperties":false}]},"import.job-createdEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.job-created"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"target":{"$ref":"#/components/schemas/ImportTargetId"},"filename":{"type":"string","minLength":1},"rows":{"type":"integer","minimum":0},"headers":{"type":"array","items":{"type":"string"}},"reference":{"type":"string","minLength":1}},"required":["jobId","target","filename","rows","headers"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.target-changedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.target-changed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"target":{"$ref":"#/components/schemas/ImportTargetId"}},"required":["jobId","target"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.mappedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.mapped"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"mapping":{"$ref":"#/components/schemas/ImportMappingEncoded"}},"required":["jobId","mapping"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.queuedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.queued"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"queuedBy":{"type":"string","minLength":1}},"required":["jobId","queuedBy"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.startedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.started"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"rows":{"type":"integer","minimum":0}},"required":["jobId","rows"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.progressedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.progressed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"progress":{"$ref":"#/components/schemas/ImportProgressEncoded"}},"required":["jobId","progress"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.rows-failedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.rows-failed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"failures":{"type":"array","items":{"$ref":"#/components/schemas/RowFailureEncoded"}}},"required":["jobId","failures"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.completedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.completed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"progress":{"$ref":"#/components/schemas/ImportProgressEncoded"}},"required":["jobId","progress"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.failedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.failed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"},"reason":{"type":"string","minLength":1},"progress":{"$ref":"#/components/schemas/ImportProgressEncoded"}},"required":["jobId","reason","progress"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.cancelledEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.cancelled"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"}},"required":["jobId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.rows-discardedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.rows-discarded"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"jobId":{"$ref":"#/components/schemas/ImpId"}},"required":["jobId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.mapping-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.mapping-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"mapping":{"$ref":"#/components/schemas/SavedMappingEncoded"}},"required":["mapping"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"import.mapping-deletedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.mapping-deleted"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"mappingId":{"$ref":"#/components/schemas/MapId"}},"required":["mappingId"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"ExportRuleEncoded":{"type":"object","properties":{"column":{"type":"string","minLength":1},"op":{"$ref":"#/components/schemas/ExportRuleOperator"},"value":{"type":"string"}},"required":["column","op"],"additionalProperties":false},"import.export-requestedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["import.export-requested"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId_1"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"exportId":{"$ref":"#/components/schemas/ExpId"},"target":{"$ref":"#/components/schemas/ExportTargetId"},"from":{"type":"string"},"to":{"type":"string"},"catalogId":{"$ref":"#/components/schemas/CatId"},"columns":{"type":"array","items":{"type":"string"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ExportRuleEncoded"}},"expiresAt":{"type":"string"}},"required":["exportId","target","columns","rules","expiresAt"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"JournalHead":{"type":"object","properties":{"at":{"type":"string"},"sequence":{"type":"integer","minimum":0}},"required":["at"],"additionalProperties":false,"description":"Where a tenant's journal stood at a moment."}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A tenant JWT: sign in through the auth service, choose the organization, then `GET /api/auth/token`. Tokens last 15 minutes."}}},"security":[],"tags":[{"name":"targets","description":"What can be imported, and the fields each target accepts."},{"name":"imports","description":"Upload, preview, map, and run CSV imports."},{"name":"mappings","description":"Reusable column mappings."},{"name":"exports","description":"Streaming CSV export, and its preview."},{"name":"events","description":"Import journal replay."}],"servers":[{"url":"https://import.getmanifold.io","description":"Production"}]}