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.
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"
  }'
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

OperationEndpoint
List projectsGET /v1/review-projects
Create projectPOST /v1/review-projects
Get projectGET /v1/review-projects/{id}
Update projectPATCH /v1/review-projects/{id}
Delete projectDELETE /v1/review-projects/{id}
List annotationsGET /v1/review-annotations
Create annotationPOST /v1/review-annotations
Get annotationGET /v1/review-annotations/{id}
Update annotationPATCH /v1/review-annotations/{id}
Delete annotationDELETE /v1/review-annotations/{id}
Need ad-hoc reviews without a project? Create a standalone annotation with POST /v1/review-annotations. Reviewers can also complete assignments in the dashboard.