Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.
Validate a mapping without saving
const url = 'https://api.eu1.luigisbox.ai/catalog/v1/example/mappings/validate';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"mapping":{},"sample":{},"trace":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.eu1.luigisbox.ai/catalog/v1/example/mappings/validate \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "mapping": {}, "sample": {}, "trace": true }'Applies the mapping to sample and returns the mapped record with a trace of every rule: the fields each rule matched, the value after each transform, and the fields each target wrote. Stores nothing. A mapping with a rule that cannot apply to any record is a 422 listing every problem in exception_details.mapping_problems. A rule that fails only on this sample — a missing @ reference, a transform that raises — is a 200 with rejection set and the failing targets marked failed; every other rule still runs. Set trace to false for only result and rejection.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
Attribute-mapping DSL as a source -> target object, e.g. {"name": "@title", "price": "price_amount | to_f"}. Keys select fields on the incoming item; each value is a target spec — an optional target field name followed by optional |-chained transform filters. Omit the name ("| to_s") to transform the field in place, or pass a list of specs to write several targets from one source. A renamed source key is moved rather than copied, so list the original name among the targets to keep it; unmapped fields pass through unchanged. The object is open: any source field name is a valid key.
object
A sample source item (arbitrary client fields) to apply the mapping to for the dry run.
object
Whether the response lists, in rules, how every rule handled the sample. false returns only result and rejection, with rules empty.
Responses
Section titled “ Responses ”Successful Response
A mapping applied to a sample, with a trace of every rule.
object
Why the mapping fails on the sample.
object
Always mapping_failed, the code ingest rejects such a record under.
The first failure in mapping order, in full. Ingest reports the same failure shortened to 80 characters with … appended.
The sample after the mapping is applied — the resulting canonical fields. When rejection is set, the mapping fails on such a record and ingest stores none of it: a failed rule’s source field is gone from it and its target absent, and fields no rule maps pass through.
object
Every rule of the mapping in the order it ran, @defaults first wherever it is placed. Empty when the request set trace to false.
One rule of the mapping, applied to the sample.
object
The rule’s key as written in the mapping, e.g. custom_* or @defaults.
One entry per field the key matched, in match order; for @defaults, one per default. Empty when status is no_match.
One field of the sample a rule’s key matched.
object
The value as the rule found it, after earlier rules ran; for an @defaults entry, the referenced value or the literal.
One entry per target spec of the rule, in the order written.
One target spec of a matched rule, transform by transform.
object
Why one target failed on the sample.
written — the value was written to target_paths; skipped_source_null — the matched field is null, so nothing is written and the source field is dropped from result; skipped_value_present — an @defaults entry for a field the record already has; skipped_reference_missing — an @defaults entry referencing a field the record lacks; discarded — the target path cannot be reached (it runs through a value that is not an object), so the value is dropped without an error and nothing is written; failed — see problem.
The fields of result the target wrote, in write order, each as a path: object keys as strings, list positions as integers, e.g. ["variants", 0, "price"]. Several when the target path crosses a list or spreads an object with .. Empty when the target was skipped; a failed target may still list the fields it wrote before it failed. A path is where the field was when the target wrote it; a later rule that empties and so drops a list element can still shift the positions after it. After an append (+) or a merge the field in result holds more than the target’s own value.
Every transform of the spec in the order it ran, up to and including one that failed.
One transform of a target spec and the value it produced.
object
The transform’s arguments as written in the target spec, e.g. ["in stock", 1, "out of stock", 0]; a reference to another field appears as written, e.g. @list_price. Empty when it takes none.
The transform’s name, e.g. to_f.
Whether the transform ran on each element of a list value rather than on the value as a whole.
The value after this transform; null when the transform failed.
The value after the last transform — what the target writes; null when the target was skipped or a transform failed. For discarded and mapping_target_conflict, the value that could not be written.
applied — the key matched and no target failed; no_match — the sample has no field the key selects; failed — a target failed on the sample.
Example
{ "rejection": { "code": "mapping_failed" }, "rules": [ { "matches": [ { "targets": [ { "problem": { "code": "mapping_reference_missing" }, "status": "written" } ] } ], "status": "applied" } ]}Missing or invalid credentials
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Authenticated but not permitted
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Request validation failed. A mapping with a rule that cannot apply to any record lists every problem at once in exception_details.mapping_problems: mapping_rule_invalid for a target spec that does not parse or an @defaults that is not an object, mapping_target_invalid for a target that is not a string, mapping_transform_unknown for an unknown transform.
Error body returned when a mapping holds rules that cannot apply to any record.
exception_details.mapping_problems lists every problem; reason names the first one.
object
Machine-readable error context: every problem found in the mapping.
object
Every problem found in one pass over the mapping, in mapping order; never truncated.
One mapping rule that cannot apply to any record.
object
Stable machine code of the problem.
The rule’s key as written in the mapping, e.g. price.
Human-readable explanation of the problem; may be reworded.
Human-readable, actionable error message.
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example
{ "exception_details": { "mapping_problems": [ { "code": "mapping_rule_invalid" } ] }}Service temporarily unavailable
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Was this page helpful?
Thanks.