Human Review via API

Use the Reviews API to create projects, assign review tasks, and submit human answers from your own application or script. This guide covers the request sequence. See the API reference for request fields and response schemas.

All requests require an X-API-Key header. See the API Keys guide for setup.

Projects, annotations, and completion

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.

An annotation represents one metric answer. Its COMPLETED status is separate from submitting a whole conversation with Review Complete in the dashboard. Do not use a single completed annotation as evidence that all of a conversation’s review requirements have been met.

Creating and completing review tasks

Create a project

POST /v1/review-projects with your simulations, metrics, and assignees. Use project_type PROJECT_COLLABORATIVE for shared review of each conversation–metric pair, 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/conversations/simulated.

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.

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. Providing a ground-truth value marks that annotation complete. The reference lists every field, including ground_truth_subvalues_by_timestamp for audio-region and per-segment metrics.

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

Improve your metrics

Compare the submitted answers with metric outputs and investigate disagreements before revising a metric.

Endpoint reference

Operation	Endpoint
List projects	`GET /v1/review-projects`
Create project	`POST /v1/review-projects`
Get project	`GET /v1/review-projects/{id}`
Update project	`PATCH /v1/review-projects/{id}`
Delete project	`DELETE /v1/review-projects/{id}`
List annotations	`GET /v1/review-annotations`
Create annotation	`POST /v1/review-annotations`
Get annotation	`GET /v1/review-annotations/{id}`
Update annotation	`PATCH /v1/review-annotations/{id}`
Delete annotation	`DELETE /v1/review-annotations/{id}`

For reviews without a project, create a standalone annotation with POST /v1/review-annotations. Reviewers can also complete assignments in the dashboard.

Simulated Conversations

Evaluate

Analyze

Review

Cookbooks

Sofia

Reference

Projects, annotations, and completion

Creating and completing review tasks

Endpoint reference

​Projects, annotations, and completion

​Creating and completing review tasks

​Endpoint reference

Projects, annotations, and completion

Creating and completing review tasks

Endpoint reference