API Feedback

API Feedback lets your system send feedback about values produced by Etals. You can use it to store feedback and ask Etals to automatically create a new task that regenerates the affected values with your feedback added as context.

You can target a value in two ways:

• By its value_id (included in the API export payload for values produced by Etals tasks).
• By referring to the property and context directly, using the same identifiers and localization the export uses. This also lets you send feedback about a value that is currently missing.

When to use API Feedback

Use API Feedback when your receiving system, reviewer, or downstream workflow identifies that a value needs improvement, or that a value that should exist is missing.

Endpoint

Send a POST request to:

POST https://{your-tenant}.etals.com/api/v1/feedback/content-job-values

The request must be authenticated with an API token that has the create ability.

Authorization: Bearer {token}
Content-Type: application/json

Request body

The request mirrors the structure of the API export payload. You provide the attributable type, the items (by identifier), the properties, and one or more values per property.

Each value can either reference a value_id, or describe its context (language, brand, market, front, country). When value_id is present, the context fields are ignored.

1
{
2
  "attributable_type": { "system_code": "products" },
3
  "items": [
4
    {
5
      "identifiers": { "identifier": "kXW46MkgGgj5" },
6
      "properties": [
7
        {
8
          "system_code": "meta_title",
9
          "values": [
10
            {
11
              "language": "en",
12
              "brand": "acme",
13
              "market": null,
14
              "feedback": "International english is required."
15
            },
16
            {
17
              "language": "en",
18
              "brand": "acme",
19
              "market": "ie",
20
              "feedback": "This phrasing is too US-centric. Rewrite for an Irish audience."
21
            }
22
          ]
23
        },
24
        {
25
          "system_code": "spaces",
26
          "values": [
27
            {
28
              "value_id": 9876,
29
              "feedback": "Not appropriate for kids rooms."
30
            }
31
          ]
32
        }
33
      ]
34
    }
35
  ]
36
}

How values are located

When value_id is omitted, Etals resolves the value before producing any task:

1. The content type is found by attributable_type.system_code.
2. The item is found by its identifier.
3. The property is found by its system_code.
4. The context (language, brand, market, front, country) is matched against an attribute item.

If no attribute item matches the provided context, the request is rejected and no tasks are created. If the attribute item exists but currently has no value, Etals still creates a task to generate it.

Response

A successful request returns a 201 response.

1
{
2
  "success": true,
3
  "message": "Feedback stored successfully",
4
  "data": {
5
    "feedbackIds": [12, 13],
6
    "createdContentJobIds": [456]
7
  }
8
}

When one or more values cannot be resolved, the request returns a 422 response and creates nothing.

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

The errors object is keyed by the index of the value in the request (counting values across all items and properties, starting at 0).

Automatic regeneration

When regeneration is requested, the new task:

• Does not reuse an existing value, so a new value is generated.
• Adds your feedback as context for the new generation.
• Is marked as a feedback task, so it appears in the dedicated Feedback activity view rather than the general activity list.

When a value is referenced by value_id, the new task reuses the original task’s settings and exports to your integration if the original task did.

When a value is referenced by context (no value_id), the new task always exports to the content type’s integration once it finishes. Etals also selects how to regenerate the value automatically: if the property has a configured pipeline it is used, otherwise Etals picks the most suitable pipeline for the content type. Because the original intent of the value is not known in this case, the task is categorized generically.

Grouping behavior

You can send feedback for several values in one request.

• Values referenced by value_id are grouped by their original task: Etals creates one new feedback task per original task.
• Values referenced by context are grouped by item: Etals creates one new feedback task per item, covering all of that item’s properties and contexts. Each feedback line is labelled with its property and context.

Example flow

1. Etals exports produced content to your endpoint.
2. Your system stores each exported value_id, or keeps the property and context.
3. A reviewer or automated check identifies an issue with a value, or a missing value.
4. Your system sends feedback to the API Feedback endpoint.
5. Etals stores the feedback and, when requested, creates a feedback task.
6. The regenerated value is exported back to your endpoint.