Skip to main content
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 has the full schema for every endpoint.
All requests require an X-API-Key header. See the API Keys guide for setup.

​
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.
Using Claude Code? We have skills to support human review in your workflow.

​
The flow

1

Create a project

POST /v1/review-projects with your simulations, metrics, and assignees. Use project_type PROJECT_COLLABORATIVE for one shared label per conversation, or PROJECT_INDIVIDUAL for per-reviewer queues.
Finding IDs: metric IDs come from GET /v1/metrics and simulation IDs from GET /v1/simulations.
2

Find the annotations

List the auto-generated annotations with GET /v1/review-annotations, filtering by project_id and completion_status to find pending work. See the reference for the full filter, paging, and sort parameters.
3

Submit ground truth

PATCH /v1/review-annotations/{id} 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.
4

Track progress

Re-fetch the project with GET /v1/review-projects/{id}, or count completed annotations via the list endpoint filtered on completion_status="COMPLETED".
5

Improve your metrics

Once labels are in, improve the metrics that disagree using the agreement scores.

​
Endpoint reference

Need ad-hoc reviews without a project? Create a standalone annotation with POST /v1/review-annotations. Reviewers can also complete assignments in the dashboard.