> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Human Review via API

> Create review projects and submit ground-truth annotations programmatically.

The Coval Reviews API lets you create review projects, assign reviewers, and submit ground-truth annotations programmatically — useful for CI/CD pipelines, bulk labeling, or a custom review surface. This page orients you; the [API reference](/api-reference/v1/reviews/review-projects/list-review-projects) has the full schema for every endpoint.

<Info>
  All requests require an `X-API-Key` header. See the [API Keys guide](/guides/api-keys) for setup.
</Info>

## Concepts

* **Review Projects** group simulations, metrics, and assignees. Creating a project auto-generates one annotation per (simulation, metric, assignee) combination.
* **Review Annotations** are the individual review tasks. Providing a ground-truth value automatically sets the annotation's `completion_status` to `COMPLETED`.

<Tip>
  Using Claude Code? We have [skills to support human review](https://github.com/coval-ai/coval-external-skills/tree/main/skills/human-review) in your workflow.
</Tip>

## The flow

<Steps>
  <Step title="Create a project">
    [`POST /v1/review-projects`](/api-reference/v1/reviews/review-projects/create-review-project) with your simulations, metrics, and assignees. Use `project_type` `PROJECT_COLLABORATIVE` for one shared label per conversation, or `PROJECT_INDIVIDUAL` for per-reviewer queues.

    ```bash theme={null}
    curl -X POST https://api.coval.dev/v1/review-projects \
      -H "X-API-Key: <your_api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "display_name": "Q1 Voice Agent Review",
        "assignees": ["alice@company.com"],
        "linked_simulation_ids": ["sim-output-001"],
        "linked_metric_ids": ["metric-accuracy"],
        "project_type": "PROJECT_COLLABORATIVE"
      }'
    ```

    <Info>
      **Finding IDs:** metric IDs come from [`GET /v1/metrics`](/api-reference/v1/metrics/metrics/list-metrics) and simulation IDs from [`GET /v1/simulations`](/api-reference/v1/simulations/simulations/list-simulations).
    </Info>
  </Step>

  <Step title="Find the annotations">
    List the auto-generated annotations with [`GET /v1/review-annotations`](/api-reference/v1/reviews/review-annotations/list-review-annotations), filtering by `project_id` and `completion_status` to find pending work. See the reference for the full filter, paging, and sort parameters.
  </Step>

  <Step title="Submit ground truth">
    [`PATCH /v1/review-annotations/{id}`](/api-reference/v1/reviews/review-annotations/update-review-annotation) with `ground_truth_float_value` (numeric metrics) or `ground_truth_string_value` (string/categorical) — plus optional `reviewer_notes`. This auto-completes the annotation. The reference lists every field, including `ground_truth_subvalues_by_timestamp` for audio-region and per-segment metrics.
  </Step>

  <Step title="Track progress">
    Re-fetch the project with [`GET /v1/review-projects/{id}`](/api-reference/v1/reviews/review-projects/get-review-project), or count completed annotations via the list endpoint filtered on `completion_status="COMPLETED"`.
  </Step>

  <Step title="Improve your metrics">
    Once labels are in, [improve the metrics that disagree](/guides/improving-metrics-with-human-review) using the agreement scores.
  </Step>
</Steps>

## Endpoint reference

| Operation         | Endpoint                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| List projects     | [`GET /v1/review-projects`](/api-reference/v1/reviews/review-projects/list-review-projects)                   |
| Create project    | [`POST /v1/review-projects`](/api-reference/v1/reviews/review-projects/create-review-project)                 |
| Get project       | [`GET /v1/review-projects/{id}`](/api-reference/v1/reviews/review-projects/get-review-project)                |
| Update project    | [`PATCH /v1/review-projects/{id}`](/api-reference/v1/reviews/review-projects/update-review-project)           |
| Delete project    | [`DELETE /v1/review-projects/{id}`](/api-reference/v1/reviews/review-projects/delete-review-project)          |
| List annotations  | [`GET /v1/review-annotations`](/api-reference/v1/reviews/review-annotations/list-review-annotations)          |
| Create annotation | [`POST /v1/review-annotations`](/api-reference/v1/reviews/review-annotations/create-review-annotation)        |
| Get annotation    | [`GET /v1/review-annotations/{id}`](/api-reference/v1/reviews/review-annotations/get-review-annotation)       |
| Update annotation | [`PATCH /v1/review-annotations/{id}`](/api-reference/v1/reviews/review-annotations/update-review-annotation)  |
| Delete annotation | [`DELETE /v1/review-annotations/{id}`](/api-reference/v1/reviews/review-annotations/delete-review-annotation) |

<Note>
  Need ad-hoc reviews without a project? Create a standalone annotation with [`POST /v1/review-annotations`](/api-reference/v1/reviews/review-annotations/create-review-annotation). Reviewers can also complete assignments [in the dashboard](/concepts/metrics/human-review/how-to-review).
</Note>