---
title: "Record Eval Feedback"
method: POST
path: "/api/platform/v1/eval-runs/{id}/feedback"
tags: ["observability"]
---

# Record Eval Feedback

`POST /api/platform/v1/eval-runs/{id}/feedback`

## Request

- Base URL: `https://docs.amdahl.ai`
- URL: `https://docs.amdahl.ai/api/platform/v1/eval-runs/{id}/feedback`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Report what happened AFTER an eval run — whether its recommendation was applied, and how you know. Call when you have acted on a report: rewritten a prompt, filed the improved copy, or decided against it. Requires evidence (did_it_myself | reported_to_me | inferred); report only what you observed, never what you assume a person did. Pass applied_to and the server checks the target actually contains it.

## Path parameters

- `id` string, required: Alias for eval_run_id, carrying the REST path segment. Pass eval_run_id; this exists so POST /eval-runs/:id/feedback resolves.

## Request body

- object
  - `eval_run_id` string: The run this feedback is about.
  - `outcome` 'used' | 'used_with_edits' | 'not_used' | 'unsure', required: What happened to the recommendation. `unsure` is a real answer and is excluded from both halves of any adoption rate — prefer it to guessing.
  - `evidence` 'did_it_myself' | 'reported_to_me' | 'inferred', required: How you know. `did_it_myself` = you performed the action in this session (the only value that can be verified). `reported_to_me` = a person told you. `inferred` = you concluded it; honest, but excluded from published rates. Never claim first-hand knowledge of something a person did outside your session.
  - `subject_key` string: What the feedback is about. Omit (or '__run__') for the run as a whole; otherwise a stable key naming one recommendation, so the same recommendation across runs can be counted together.
  - `what_happened` string: Free text, unconstrained. Say what you actually did, or why the recommendation was not usable — the reason is worth more than the verdict.
  - `applied_to` object: Where it was applied, e.g. { "kind": "agent", "id": "<uuid>" }. Recognised kinds (agent, routine, knowledge_doc) are dereferenced and checked; anything else is stored unverified rather than rejected.

## Response `200`

OK

- object
  - `data` object, required
    - `success` boolean, required
    - `feedback_id` string
    - `created` boolean: False when this replaced your earlier verdict on the same subject.
    - `verified` boolean, nullable: Three-state. true = the server found the recommendation in applied_to. false = it checked and it is absent. null = nothing was checked. null and false are different answers and must not be collapsed.
    - `verification_note` string, nullable

## Other responses

- `400`: Invalid input - failed schema validation
- `401`: Authentication required
- `403`: Forbidden - missing scope or role
- `500`: Internal server error

---

[API](https://skmtc.dev/amdahl/apis/amdahl-platform-api.md) · [All operations](https://skmtc.dev/amdahl/apis/amdahl-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/amdahl/apis/amdahl-platform-api/revisions/d4eee33e2472?raw)