curl --request POST \
--url https://api.coval.dev/v1/review-annotations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"simulation_output_id": "sim-output-abc123",
"metric_id": "metric-accuracy-001",
"assignee": "reviewer@company.com"
}
'{
"review_annotation": {
"name": "review-annotations/abc123def456ghi789jklm",
"id": "abc123def456ghi789jklm",
"simulation_output_id": "<string>",
"metric_id": "<string>",
"assignee": "<string>",
"status": "ACTIVE",
"completion_status": "PENDING",
"priority": "PRIORITY_STANDARD",
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"assignee_user_id": "<string>",
"ground_truth_float_value": 123,
"ground_truth_string_value": "<string>",
"ground_truth_subvalues_by_timestamp": [
{}
],
"reviewer_notes": "<string>",
"annotations": {},
"canonical_annotation_id": "<string>",
"ground_truth_json": {},
"ground_truth_set_value": [
"<string>"
],
"project_annotation_id": "<string>"
}
}{
"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": "NOT_FOUND",
"message": "Resource not found",
"details": [
{
"field": "annotation_id",
"description": "Annotation not found or not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Reviews
Create review annotation
Create a new review annotation for your organization.
POST
/
review-annotations
curl --request POST \
--url https://api.coval.dev/v1/review-annotations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"simulation_output_id": "sim-output-abc123",
"metric_id": "metric-accuracy-001",
"assignee": "reviewer@company.com"
}
'{
"review_annotation": {
"name": "review-annotations/abc123def456ghi789jklm",
"id": "abc123def456ghi789jklm",
"simulation_output_id": "<string>",
"metric_id": "<string>",
"assignee": "<string>",
"status": "ACTIVE",
"completion_status": "PENDING",
"priority": "PRIORITY_STANDARD",
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"assignee_user_id": "<string>",
"ground_truth_float_value": 123,
"ground_truth_string_value": "<string>",
"ground_truth_subvalues_by_timestamp": [
{}
],
"reviewer_notes": "<string>",
"annotations": {},
"canonical_annotation_id": "<string>",
"ground_truth_json": {},
"ground_truth_set_value": [
"<string>"
],
"project_annotation_id": "<string>"
}
}{
"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": "NOT_FOUND",
"message": "Resource not found",
"details": [
{
"field": "annotation_id",
"description": "Annotation not found or not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Authorizations
Organization API key for authentication
Query Parameters
Optional project ID to apply project-rule-aware completion status
Body
application/json
Simulation output ID to link
Minimum string length:
1Metric ID to link
Minimum string length:
1Optional Coval reviewer User ULID, validated against organization membership. Null preserves email-based writes or uses authenticated self-review.
Required string length:
26Legacy reviewer email; accepted without a matching user. New answers receive a User ID when safely resolved.
Minimum string length:
1Optional ground truth numeric value (auto-completes annotation)
Optional ground truth string value (auto-completes annotation)
Optional ground truth subvalues
Optional reviewer notes
Response
Annotation created successfully
A single review annotation resource.
Show child attributes
Show child attributes
Was this page helpful?