> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Create an annotation"
description: "Record a human review label on a run item, stored next to the scorer results."
method: "POST"
endpoint: "/api/v1/projects/:projectId/eval/runs/:runId/items/:runItemId/annotations"
order: 19
group: "Review and rescore"
last_verified: 2026-10-08
---



`POST /api/v1/projects/:projectId/eval/runs/:runId/items/:runItemId/annotations`

Record a human review label on a run item, stored next to the scorer results.


  ## Parameters

  - `projectId` _string_ **required** — The project UUID.
  - `runId` _string_ **required** — The experiment run UUID.
  - `runItemId` _string_ **required** — The run item UUID, from Run failures or the run items.
  - `label` _string_ **required** — The reviewer verdict, for example `pass`, `fail`, or `partial`.
  - `name` _string_ — The annotation name. Default `human_label`.
  - `metadata` _object_ — Reviewer notes as a JSON object.



  ## Request example


```bash
curl -X POST "https://api.agnt5.com/api/v1/projects/{project_id}/eval/runs/{run_id}/items/{run_item_id}/annotations" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {api_key}" \
  -d '{"name": "human_label", "label": "pass", "metadata": {"reviewer": "alice", "note": "Correct order ID cited"}}'
```

```javascript
fetch('https://api.agnt5.com/api/v1/projects/' + projectId + '/eval/runs/' + runId + '/items/' + runItemId + '/annotations', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-KEY': apiKey },
  body: JSON.stringify({ label: 'pass', metadata: { reviewer: 'alice' } })
})
```


  ```json {{ title: 'Response (201 Created)' }}
  {
    "success": true,
    "message": "Annotation created",
    "data": {
      "id": "3d1d42be-...",
      "experiment_run_id": "9b2c4d6e-...",
      "run_item_id": "284a65e6-...",
      "name": "human_label",
      "annotator_kind": "HUMAN",
      "source": "API",
      "label": "pass",
      "metadata": { "reviewer": "alice", "note": "Correct order ID cited" },
      "created_at": 1791493555997
    }
  }
  ```