> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.etals.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.etals.com/_mcp/server. # 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](/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: ```text 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. ```text Authorization: Bearer {token} Content-Type: application/json ``` ## Request body The request mirrors the structure of the [API export](/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. ```json { "attributable_type": { "system_code": "products" }, "items": [ { "identifiers": { "identifier": "kXW46MkgGgj5" }, "properties": [ { "system_code": "meta_title", "values": [ { "language": "en", "brand": "acme", "market": null, "feedback": "International english is required." }, { "language": "en", "brand": "acme", "market": "ie", "feedback": "This phrasing is too US-centric. Rewrite for an Irish audience." } ] }, { "system_code": "spaces", "values": [ { "value_id": 9876, "feedback": "Not appropriate for kids rooms." } ] } ] } ] } ``` | Field | Description | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `attributable_type.system_code` | The system code of the content type (for example `products`). Required when any value omits `value_id`. | | `items` | A list of items. At least one item is required. | | `items[].identifiers.identifier` | The identifier of the item (for example its product number or URL). Required when a value omits `value_id`. | | `items[].properties` | A list of properties for the item. At least one is required. | | `items[].properties[].system_code` | The system code of the property. Required when a value omits `value_id`. | | `items[].properties[].values` | A list of values for the property. At least one is required. | | `items[].properties[].values[].value_id` | Optional. The `value_id` from the export payload. When provided, the context fields are ignored. | | `items[].properties[].values[].language` / `brand` / `market` / `front` / `country` | Optional context system codes used to locate the value when `value_id` is not provided. An explicit `null` means "this dimension is null"; omitting a field means it does not apply. | | `items[].properties[].values[].feedback` | The feedback text. Required. | | `items[].properties[].values[].create_content_job` | Optional. When `true` (the default), Etals creates a new task that regenerates the value. When `false`, the feedback is stored without creating a task. | ## 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. ```json { "success": true, "message": "Feedback stored successfully", "data": { "feedbackIds": [12, 13], "createdContentJobIds": [456] } } ``` | Field | Description | | --------------------------- | --------------------------------------------------------------------------------------------------- | | `data.feedbackIds` | The IDs of the stored feedback records. | | `data.createdContentJobIds` | The IDs of any automatically created tasks. This can be empty when no value requested regeneration. | When one or more values cannot be resolved, the request returns a `422` response and creates nothing. ```json { "success": false, "message": "Some feedback items could not be resolved", "errors": { "0": "No attribute item matches the provided context for property \"meta_title\"" } } ``` 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.