API Feedback

The Feedback API is the optional return leg of the round trip. When a reviewer or an automated check in your system finds a problem with a value Etals sent you, you post the feedback back. Etals stores it and, unless you say otherwise, creates a new task that writes the value again with your feedback as extra instructions.

You can point at a value in two ways:

• By value_id, the ID that came with the value in the API export payload.
• By context: content type, item identifier, property and localization. This also works for a value that does not exist yet, so you can report missing content.

Endpoint

POST https://{your-workspace}.etals.app/api/v1/feedback/content-job-values
Authorization: Bearer {api-token}
Content-Type: application/json
Accept: application/json

The token needs the Create ability. No extra user permission is needed. See Authorization.

Request body

The body uses the same shape as the export payload, with feedback in place of value.

{
  "attributable_type": { "system_code": "products" },
  "items": [
    {
      "identifiers": { "identifier": "NV-1001" },
      "properties": [
        {
          "system_code": "description",
          "values": [
            {
              "value_id": 457,
              "feedback": "Mention that the jacket weighs 410 g. Customers ask about the weight."
            }
          ]
        },
        {
          "system_code": "meta_title",
          "values": [
            {
              "language": "de",
              "market": "de",
              "feedback": "The German meta title is missing. Write one, max 60 characters."
            },
            {
              "language": "en",
              "market": "uk",
              "feedback": "Use British English and drop the brand name.",
              "create_content_job": false
            }
          ]
        }
      ]
    }
  ]
}

How a value is found

With a value_id, Etals looks up that produced value. If the ID does not exist, the request fails.

Without a value_id, Etals resolves the target step by step:

1. The content type, by attributable_type.system_code.
2. The item, by identifier.
3. The property, by its system_code within that content type.
4. The localization, from the context fields.

For the context fields:

• A field you send with a code ("language": "de") must match exactly.
• A field you send as null means “this localization has no value for that dimension”, and must match exactly.
• A field you leave out is first treated as null. If no localization matches that way, Etals ignores the field and accepts the match only if exactly one localization fits.
• If more than one localization still fits, the request fails and asks for more context, for example front.

If the localization exists but has no value yet, the feedback is still accepted and the new task writes the missing value.

Responses

Created

201 Created. Feedback is stored for every value in the request.

{
  "success": true,
  "message": "Feedback stored successfully",
  "data": {
    "feedbackIds": [311, 312, 313],
    "createdContentJobIds": [1408, 1409],
    "skipped": [],
    "failed": []
  }
}

Skipped and failed feedback is kept. Etals tries to create the task again every 5 minutes, so it goes through once a pipeline has been set up for the property.

Some values could not be resolved

422 Unprocessable Entity. Nothing is stored and no task is created, even for the values that were fine.

{
  "success": false,
  "message": "Some feedback items could not be resolved",
  "errors": {
    "1": "No attribute item matches the provided context for property \"meta_title\""
  }
}

errors is keyed by the position of the value in the request, counting all values across all items and properties, starting at 0. Possible messages:

Invalid body

422 Unprocessable Entity in the standard validation format, for example when feedback is missing:

{
  "message": "Feedback text is required for each value",
  "errors": {
    "items.0.properties.0.values.0.feedback": ["Feedback text is required for each value"]
  }
}

Server error

500 with {"success": false, "message": "Failed to store feedback: {reason}"}.

The regeneration task

When create_content_job is true, the new task:

• Writes a new value instead of reusing the current one, with your feedback added to its instructions.
• Is named [Feedback] ... and is marked as a feedback task.
• Runs without an approval step.
• Picks its pipeline from the property: the pipeline set on the property if there is one, otherwise the only pipeline attached to it, otherwise the best match among the attached pipelines. If none fits, the feedback is skipped (see above).

What else it does depends on how you pointed at the value:

The regenerated value arrives at your receiver as a normal API export, with a new value_id.

Example flow

1. Etals exports the English description of NV-1001 to your endpoint with value_id 457.
2. Your reviewer notes that the weight is missing.
3. Your system posts the feedback with value_id: 457.
4. Etals answers 201 and creates a feedback task.
5. When the task finishes, the new description reaches your endpoint with a new value_id.