Runs the transformation on the file sent as multipart field file instead of fetching its feed, then submits the result: a new submission is created and the template's deliveries fire. For a source built from several files, send one file[<file handle>] per file to replace: the others keep their last file, and every file is merged again. Asynchronous: the call returns a run (step = pending); poll GET /transformation/automation/{automationId} until step is processed or failed.

Optional form field email: an address that receives the success/error report when the run ends, whatever the schedule's notification settings. For uploaded-file runs, original_file is always null. Returns 400 for an invalid email, 409 for a missing or too large file, and 429 while a run of this transformation that started less than an hour ago is still going.

sequenceDiagram
    title Running a transformation and following it
    participant c as Your system
    participant w as WeTransform API
    c ->> w: Run on the source feed [1] (or on an uploaded file {link:upload})
    w -->> c: automation_id, step = pending
    loop until step is processed or failed
        c ->> w: Get the status of the run [2]
    end
POST https://api.wetransform.com/transformation/automation/{transformationId}/upload
URL Parameters
Parameter Description
{transformationId}

UUID of the transformation to run on the uploaded file.

File Upload
TransformationPublicTransformUpload

File uploads must use the regular HTTP multipart/form-data body encoding.

Multipart form: file (required), the source file to transform — or one file[<file handle>] per file for a source built from several files; email (optional), an address that receives the success/error report when the run ends.

Field name Description Constraints
file[]

The source file to transform, as file. For a transformation whose source is built from several files, send one file[<file handle>] per file to replace instead (the handles are listed by the source's files endpoint); the others keep their last file. Same formats as a manual upload (CSV, Excel, JSON, XML...), up to 1 GB each.

Not Blank
Responses
Response 200
ResponseSuccess ScheduleAutomation
success boolean

Always true on successful responses.

Sample: true
payload object

Payload of the requested resource.

payload.automation_id string nullable

UUID of this run. Pass it to GET /transformation/automation/{automationId} to follow it.

Sample: "ebb51a30-728a-4708-96ce-45ff38b63bea"
payload.type string nullable

What started the run: api (run or upload endpoint), schedule (the transformation's schedule) or email (a file sent to the transformation's mailbox).

Sample: "api"
payload.step string nullable

Where the run is. In order: pending, to_download, downloading, to_normalize, normalizing, to_parse, parsing, to_import, importing, to_create, creating, to_transform, transforming, to_submit, submitting, then one of the two final values: processed (success) or failed. A run started from an upload skips the download steps.

Sample: "pending"
payload.step_for_humans object nullable

The step, as a sentence for display, translated in the request's language.

payload.step_for_humans.code string

A translation key for the given message.

Sample: "source.event.pending"
payload.step_for_humans.message string object

The translated version of the message.

Click on "Example" to get its translated value.

payload.details string nullable

Null while the run progresses normally. On failed, the reason, in the request's language.

While downloading from a custom extractor, a note that the run waits for the extractor's callback.

payload.original_file string nullable

Signed link (valid 30 days, no authentication) to the source file this run fetched. Null until the run's submission exists, and always null for uploaded-file runs.

Sample: "https:\/\/example.com\/original-file.csv"
payload.transformed_file string nullable

Signed link (valid 30 days, no authentication) to the file this run produced. Null until the run has submitted it.

Sample: "https:\/\/example.com\/transformed-file.csv"
payload.error_report_file string nullable

Signed link (valid 30 days, no authentication) to the run's validation error report, a CSV with one line per error. Null when there is none.

Sample: "https:\/\/example.com\/error-report-file.csv"
payload.created_at datetime

When the run was started.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": true,
    "payload": {
        "automation_id": "ebb51a30-728a-4708-96ce-45ff38b63bea",
        "type": "api",
        "step": "pending",
        "step_for_humans": {
            "code": "source.event.pending",
            "message": "Process execution queued."
        },
        "details": null,
        "original_file": "https:\/\/example.com\/original-file.csv",
        "transformed_file": "https:\/\/example.com\/transformed-file.csv",
        "error_report_file": "https:\/\/example.com\/error-report-file.csv",
        "created_at": "2026-10-26T10:54:45+00:00"
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 400 The `email` form field is not a valid email address.
ResponseError HttpBadRequest

The client sent an unexpected request.

It happens if the client sent an invalid JSON payload, or if the JSON payload cannot be mapped to the expected request object.

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 409 The source is built from several files: send each as `file[<file handle>]`.
ResponseError ExceptionSlotRequired

A plain file pushed to a multi-file source: each file must name its slot, file[<handle>] (WT-3593).

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

payload.code string

A translation key for the given message.

Sample: "violations.source_slot.slot_required"
payload.message string object

The translated version of the message.

Click on "Example" to get its translated value.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": {
        "code": "violations.source_slot.slot_required",
        "message": "This source is built from several files: send each one as \"file[<file handle>]\"."
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 409 A `file[<file handle>]` names a file the source does not have.
ResponseError ExceptionUnknownSlot

Files pushed to slots (file[<handle>]) that the multi-file source does not have (WT-3593).

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

payload.code string

A translation key for the given message.

Sample: "violations.source_slot.unknown"
payload.message string object

The translated version of the message.

Click on "Example" to get its translated value.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": {
        "code": "violations.source_slot.unknown",
        "message": "This source has no file named: salaries."
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 409 The source is built from one file: send it as `file`.
ResponseError ExceptionSlotsOnSingleFileSource

Files pushed to slots (file[<handle>]) of a source built from one file, which takes a plain file (WT-3593).

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

payload.code string

A translation key for the given message.

Sample: "violations.source_slot.single_file"
payload.message string object

The translated version of the message.

Click on "Example" to get its translated value.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": {
        "code": "violations.source_slot.single_file",
        "message": "This source is built from one file: send it as \"file\"."
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 429 A run of this transformation started less than an hour ago and has not finished yet.
ResponseError ExceptionTransformationAlreadyInProgress
success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

payload.code string

A translation key for the given message.

Sample: "automation.transformation_already_running"
payload.message string object

The translated version of the message.

Click on "Example" to get its translated value.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": {
        "code": "automation.transformation_already_running",
        "message": "A transformation is already in progress, you need to wait for it to finish before starting a new one."
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 401 Authentication required.
ResponseError HttpUnauthorized

User must be authenticated to access the resource.

This response is received when the authorization header does not contain a valid authentication token.

It mostly happens because the current access_token has expired, and it needs to be renewed using a refresh_token.

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 403 Access denied.
ResponseError HttpForbidden

User is well authenticated, but not authorized to access the resource.

It can happen if user is trying to use a feature that s/he didn't pay for, access someone else's resource, etc.

These issues are normally fixed by the frontend, which should render features and resources user has access to.

success boolean

Always false on error responses.

Sample: false
payload object

Context about the error, if any.

product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.

product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).

product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Back to API Reference

Interactive Console

Please login in order to access the console.

© 2026