curl --request POST \
--url https://api.coval.dev/v1/review-projects \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "Q1 Voice Agent Review",
"assignees": [
"alice@company.com",
"bob@company.com"
],
"linked_simulation_ids": [
"sim-output-001",
"sim-output-002"
],
"linked_metric_ids": [
"metric-accuracy",
"metric-latency"
]
}
'import requests
url = "https://api.coval.dev/v1/review-projects"
payload = {
"display_name": "Q1 Voice Agent Review",
"assignees": ["alice@company.com", "bob@company.com"],
"linked_simulation_ids": ["sim-output-001", "sim-output-002"],
"linked_metric_ids": ["metric-accuracy", "metric-latency"]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
display_name: 'Q1 Voice Agent Review',
assignees: ['alice@company.com', 'bob@company.com'],
linked_simulation_ids: ['sim-output-001', 'sim-output-002'],
linked_metric_ids: ['metric-accuracy', 'metric-latency']
})
};
fetch('https://api.coval.dev/v1/review-projects', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/review-projects",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'display_name' => 'Q1 Voice Agent Review',
'assignees' => [
'alice@company.com',
'bob@company.com'
],
'linked_simulation_ids' => [
'sim-output-001',
'sim-output-002'
],
'linked_metric_ids' => [
'metric-accuracy',
'metric-latency'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/review-projects"
payload := strings.NewReader("{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coval.dev/v1/review-projects")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/review-projects")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"review_project": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "review-projects/01HXYZ1234567890ABCDEF",
"id": "01HXYZ1234567890ABCDEF",
"display_name": "<string>",
"assignees": [
"<string>"
],
"linked_simulation_ids": [
"<string>"
],
"linked_metric_ids": [
"<string>"
],
"project_type": "PROJECT_INDIVIDUAL",
"notifications": true,
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"reviewer_user_ids": {},
"opted_out_assignee_user_ids": [
"<string>"
],
"description": "<string>",
"project_rules": [
"require_disagreement_notes"
],
"enforced_collaboration": false,
"allow_metric_skipping": false,
"blind_labeling_shown_metric_ids": [
"<string>"
],
"linked_metric_count": 0,
"linked_simulation_count": 0,
"review_label_enabled": true,
"review_label_input_mode": "OPTION_ONLY",
"review_label_options": [
"<string>"
],
"review_label_selection_mode": "SINGLE"
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "simulation_output_id",
"description": "simulation_output_id is required"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Create review project
Create a new review project. Automatically generates annotations for every (simulation, metric, assignee) combination.
curl --request POST \
--url https://api.coval.dev/v1/review-projects \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "Q1 Voice Agent Review",
"assignees": [
"alice@company.com",
"bob@company.com"
],
"linked_simulation_ids": [
"sim-output-001",
"sim-output-002"
],
"linked_metric_ids": [
"metric-accuracy",
"metric-latency"
]
}
'import requests
url = "https://api.coval.dev/v1/review-projects"
payload = {
"display_name": "Q1 Voice Agent Review",
"assignees": ["alice@company.com", "bob@company.com"],
"linked_simulation_ids": ["sim-output-001", "sim-output-002"],
"linked_metric_ids": ["metric-accuracy", "metric-latency"]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
display_name: 'Q1 Voice Agent Review',
assignees: ['alice@company.com', 'bob@company.com'],
linked_simulation_ids: ['sim-output-001', 'sim-output-002'],
linked_metric_ids: ['metric-accuracy', 'metric-latency']
})
};
fetch('https://api.coval.dev/v1/review-projects', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/review-projects",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'display_name' => 'Q1 Voice Agent Review',
'assignees' => [
'alice@company.com',
'bob@company.com'
],
'linked_simulation_ids' => [
'sim-output-001',
'sim-output-002'
],
'linked_metric_ids' => [
'metric-accuracy',
'metric-latency'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/review-projects"
payload := strings.NewReader("{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coval.dev/v1/review-projects")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/review-projects")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"display_name\": \"Q1 Voice Agent Review\",\n \"assignees\": [\n \"alice@company.com\",\n \"bob@company.com\"\n ],\n \"linked_simulation_ids\": [\n \"sim-output-001\",\n \"sim-output-002\"\n ],\n \"linked_metric_ids\": [\n \"metric-accuracy\",\n \"metric-latency\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"review_project": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "review-projects/01HXYZ1234567890ABCDEF",
"id": "01HXYZ1234567890ABCDEF",
"display_name": "<string>",
"assignees": [
"<string>"
],
"linked_simulation_ids": [
"<string>"
],
"linked_metric_ids": [
"<string>"
],
"project_type": "PROJECT_INDIVIDUAL",
"notifications": true,
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"reviewer_user_ids": {},
"opted_out_assignee_user_ids": [
"<string>"
],
"description": "<string>",
"project_rules": [
"require_disagreement_notes"
],
"enforced_collaboration": false,
"allow_metric_skipping": false,
"blind_labeling_shown_metric_ids": [
"<string>"
],
"linked_metric_count": 0,
"linked_simulation_count": 0,
"review_label_enabled": true,
"review_label_input_mode": "OPTION_ONLY",
"review_label_options": [
"<string>"
],
"review_label_selection_mode": "SINGLE"
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "simulation_output_id",
"description": "simulation_output_id is required"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Authorizations
Organization API key for authentication
Headers
Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.
1 - 26Body
- Option 1
- Option 2
Select at least one reviewer by legacy email or verified Coval User ID. Nonempty emails and User IDs cannot be combined.
Legacy reviewer emails; optional when assignee_user_ids selects the reviewers.
1Project name
1 - 200Verified Coval reviewer User IDs. Null uses the legacy email path.
1 - 1000 elements26Optional project description
Simulation output IDs (at least one required)
1Metric IDs (at least one required)
1 - 25 elementsProject type: COLLABORATIVE (shared annotations) or INDIVIDUAL (per-assignee annotations)
PROJECT_COLLABORATIVE, PROJECT_INDIVIDUAL Enable notifications for assignees
Rules to apply to this project
Project rule: require_disagreement_notes requires reviewer notes when ground truth disagrees with model output
require_disagreement_notes Metric IDs whose machine score stays visible during blind labeling
Enforce claims and explicit single-author completion for collaborative projects
Allow reviewers to skip linked metrics
False pauses conversation triage for everyone while preserving categories, modes, and saved labels. True enables triage. Null uses legacy configuration-based activation.
OPTION_ONLY, CUSTOM_ONLY, OPTION_OR_CUSTOM SINGLE, MULTIPLE Response
Project created successfully
A single review project resource.
Show child attributes
Show child attributes
Was this page helpful?