Start a full ingest run
const url = 'http://localhost:8080/v1/ingest/runs';const options = { method: 'POST', headers: { 'X-Antares-Environment-Fingerprint': 'example', 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"channel":"example","lang":"example","reason":"initial","defaultCurrency":"EUR","currencies":["EUR"],"priceContexts":[{"ctx":"c0193d1ae60d471e7d0712efda7de10115a","label":"example","customerGroupId":"example","ruleIds":["example"],"tierBoundaries":[1]}],"expectedCount":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/ingest/runs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --header 'X-Antares-Environment-Fingerprint: example' \ --data '{ "channel": "example", "lang": "example", "reason": "initial", "defaultCurrency": "EUR", "currencies": [ "EUR" ], "priceContexts": [ { "ctx": "c0193d1ae60d471e7d0712efda7de10115a", "label": "example", "customerGroupId": "example", "ruleIds": [ "example" ], "tierBoundaries": [ 1 ] } ], "expectedCount": 1 }'Opens a shadow collection for one (channel, lang) and fixes the currency assignment and price-context registry the run’s batches are validated against. Exactly one run may be open per collection.
Authorizations
Abschnitt betitelt „Authorizations“Parameters
Abschnitt betitelt „Parameters“Header Parameters
Abschnitt betitelt „Header Parameters“SHA-256 over the shop’s APP_URL plus its platform version. APP_URL lives in .env and is not carried by a database dump, which is exactly why it is the discriminator between a production install and a clone of it.
Caller-generated key. Replaying the same key with the same body replays the stored response; replaying it with a different body is 409 idempotency_conflict.
Request Bodyrequired
Abschnitt betitelt „Request Bodyrequired“Opens a full run and fixes the currency assignment and price-context registry its batches are validated against, so a batch cannot silently disagree with the run it belongs to.
object
Why a full run exists. initial — the first run after connect. schema — the document shape changed, so every document must be rewritten. reembed — vectors are recomputed from the live collection without a connector roundtrip. manual — the merchant pressed the button.
The channel’s own currency. Must equal the channel’s stored default.
Every currency the sales channel assigns, defaultCurrency first. Reconciled into the channel’s stored assignment when the run opens.
The channel’s price-context registry, upserted idempotently.
One entry of the channel’s price-context registry, carrying the structured input of the fingerprint rather than the canonical string. The API rebuilds the canonical string from these fields, hashes it, and compares the result to ctx; a mismatch fails the whole batch with price_context_fingerprint_mismatch. That comparison is the only mechanism that catches a PHP↔Go disagreement on the day it appears instead of six months later in a support ticket about wrong prices.
object
The fingerprint the connector computed. The literal default must not appear here: the default context is implicit and always exists.
Merchant-facing description of the situation, for example Händler B2B · Preisliste 2026. Panel only, never reaches the widget, and deliberately not part of the fingerprint so renaming a price list does not orphan every materialised price field.
The raw platform customer-group id, as the platform spells it. Omit it when the platform has no customer groups. The API normalises it (trim, ASCII-only case fold, remove every -) before hashing, so the dashed and undashed spellings of the same UUID are the same context.
The raw platform ids of the price rules that matched for this situation, in any order. The API normalises, deduplicates and sorts them, so the platform’s priority ordering — which is meaningless for identity — never reaches the fingerprint.
Quantity thresholds contributed by this context’s own quantity-conditioned price rules, which make the matching rule set itself quantity-dependent. The value 1 is dropped because quantity 1 is always implied. Not the per-product price ladder: that is per (product, rule), varies from product to product, and lives in PriceContext.tiers as a value inside the context.
How many products the connector intends to send. The only way the progress stream can report a percentage and an ETA instead of a growing counter, and the input to the commit-time document-count sanity check.
Responses
Abschnitt betitelt „Responses“Shadow collection created.
The connector’s view of a run, keyed by channel key rather than by UUID.
object
created — the shadow collection exists and no batch has landed. indexing — at least one batch was accepted. committed — sanity checks passed and the alias was swapped. aborted — the run failed or was superseded; the previous collection stayed live.
Documents written to the shadow collection so far.
What the connector announced when it opened the run, if it did.
Index of the last accepted batch, -1 before the first. A connector resuming after a crash sends lastBatchIndex + 1.
Products refused by validation during this run. The detail is in GET /v1/admin/index-runs/{runId}/errors.
Documents embedded so far. Only moves after the alias swap, because embedding is the second phase.
Whether the collection’s vectors are complete, so a hybrid query will hit populated vectors rather than silently return an empty vector side. Flipped by the embedding worker, per collection.
The embedding model the collection was built with. Absent until the first embedding pass. A model change requires a rebuild, because the dimension is part of the Typesense collection schema.
Version of the text template the embeddings were produced from.
Vector dimension of the collection.
Failure detail for an aborted run. Absent otherwise.
Example
{ "status": "created"}contract_validation_failed — the OpenAPI request validator rejected the request before the handler ran — or invalid_request when the body is unreadable or is not valid JSON for the declared operation.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}unauthorized — the credential is missing, malformed, unknown or revoked. For /v1/admin this also covers an actor JWS that fails signature, exp or kid verification, and a kid that no key in the panel’s JWKS matches.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}quota_exceeded — a hard cap was reached (sandbox plan, or a trial past its grace window); paid plans get the soft cap instead, which is 200 plus X-Antares-Quota: exceeded. Or plan_feature_unavailable — the organization’s resolved entitlements do not include the requested feature.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}One of index_run_active (a full run is already open for this channel and language), index_run_closed (batch or commit against a committed or aborted run), batch_out_of_order (batchIndex is not lastBatchIndex + 1 and not an exact replay), batch_conflict (the batch could not be recorded idempotently), idempotency_conflict (the same Idempotency-Key with a different body) or environment_mismatch.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}request_too_large — the body exceeds this endpoint’s byte limit. Also returned for chunked bodies without Content-Length once the limit is passed mid-stream.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}One of validation_failed (envelope-level failure, or one or more products failed; errors[] carries productIndex and no partial batch is committed), channel_not_found (the (channel, lang) pair is not mapped for this shop), currency_not_indexed (a product prices a currency the channel does not assign), price_context_fingerprint_mismatch (the API recomputed the fingerprint from the registry entry’s structured input and got a different value — the PHP↔Go drift alarm, which fails the whole batch), price_context_budget_exceeded (more than 64 contexts or more than 128 context × currency families on one product) or document_count_sanity_failed (a commit would drop the live document count below 50 % of the previous run; the old collection stays live).
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}One of rate_limit_exceeded, authentication_admission_full (the pre-auth admission guard for large connector bodies), connector_admission_full (this sk already occupies its single large-body slot) or request_admission_full (global large-body validation slots exhausted). All three admission codes are retryable after a short backoff.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}Headers
Abschnitt betitelt „Headers“Seconds to wait before retrying.
internal_error — unhandled failure. detail is always generic; the cause goes to the log with a correlation id.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}search_backend_unavailable — Typesense failed an ingest, alias, synonym or collection operation.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}One of idempotency_unavailable (the idempotency advisory lock could not be taken), index_lock_unavailable (the per-channel advisory lock could not be taken), analytics_unavailable (ClickHouse rejected a synchronous, business-critical write) or service_unavailable. All are retryable.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}