POST /v1/feedback

Record feedback on a recall result. Three feedback shapes are accepted, each suited to a different signal source:

• explicit — a thumbs-up / thumbs-down on a specific result.
• utilization — which results an agent actually used in its downstream answer.
• task_outcome — whether the task that consumed the recall ultimately succeeded.

Feedback is recorded asynchronously and used by the coordinator for online ranking refinement.

Request

POST /v1/feedback
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "recall_query": "What database are we using for payments?",
  "feedback_type": "utilization",
  "utilized_result_indices": [0, 2],
  "task_id": "qa-batch-2026-05-14-001",
  "success": true
}

| Field | Type | Required | Description | |---|---|---|---| | recall_query | string | Yes | The query string that produced the recall being rated | | feedback_type | string | No | explicit, utilization, or task_outcome | | result_index | integer | No | Index of the rated result (for explicit feedback) | | utilized_result_indices | integer[] | No | Indices of results the caller actually used | | feedback | string | No | Free-form text feedback | | tenant_id | string | No | Sub-tenant scope | | task_id | string | No | Client-supplied task correlator | | success | boolean | No | Did the downstream task succeed? (for task_outcome) | | partial_score | float | No | 0.0–1.0 partial-credit score (for task_outcome) | | comment | string | No | Operator note |

Response

{
  "recorded": true,
  "feedback_id": "01912a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"
}