Validate and commit a full ingest run
const url = 'http://localhost:8080/v1/ingest/runs/example/commit';const options = { method: 'POST', headers: { 'X-Antares-Environment-Fingerprint': 'example', 'Idempotency-Key': 'example', Authorization: 'Bearer <token>' }};
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/example/commit \ --header 'Authorization: Bearer <token>' \ --header 'Idempotency-Key: example' \ --header 'X-Antares-Environment-Fingerprint: example'Runs the sanity checks, swaps the alias and keeps the previous collection for 24 hours as the rollback window. Keyword search is live the moment this returns; embeddings continue in the background and flip hybridReady when they finish.
Authorizations
Abschnitt betitelt „Authorizations“Parameters
Abschnitt betitelt „Parameters“Path Parameters
Abschnitt betitelt „Path Parameters“Index run identifier, a ULID with an ir_ prefix.
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.
Responses
Abschnitt betitelt „Responses“Sanity checks passed and alias atomically swapped.
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 } ]}index_run_not_found — unknown runId, or the run belongs to another shop.
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 } ]}