curl --request PATCH \
--url https://api.coval.dev/v1/reports/{report_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "Q2 plan comparison"
}
'{
"report": {
"id": "01JABCDEFGHJKMNPQRSTVWXYZ0",
"created_at": null,
"created_by": null,
"updated_by": "01J000000000000000000000002",
"name": "Agent Outcomes",
"run_ids": [],
"simulation_output_ids": [],
"source_human_review_project_id": null,
"compare_by": "metadata",
"metadata_key": "rbi_vendor",
"permissions": "PRIVATE",
"updated_at": "2026-07-29T18:24:09.654321Z",
"revision": "2026-07-29T18:24:09.654321Z",
"view_config": {
"is_monitoring": true,
"compare_by": "metadata",
"metadata_key": "rbi_vendor",
"custom_dimension_id": null,
"view_mode": "grouped",
"secondary_compare_by": "none",
"secondary_metadata_key": null,
"secondary_custom_dimension_id": null,
"custom_dimensions": [],
"monitoring_filters": {
"start_date": "2026-07-01T00:00:00.000000Z",
"end_date": "2026-08-01T00:00:00.000000Z",
"monitoring_filter": true
}
},
"metric_config": {
"01JMETRICABCDEFGHJKMNPQRS": {
"visible": true,
"passing_threshold": 0.8
}
}
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "metadata_key",
"description": "metadata_key is required when compare_by is metadata"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "x-api-key",
"description": "API key is required in the x-api-key header"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Insufficient permissions",
"details": [
{
"field": "permissions",
"description": "The API key does not include the required report permission."
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Report not found",
"details": [
{
"field": "report_id",
"description": "Report not found or not authorized."
}
]
}
}{
"error": {
"code": "FAILED_PRECONDITION",
"message": "Report revision is stale",
"details": [
{
"field": "If-Match",
"description": "Report configuration changed after it was read. Fetch the report and retry."
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred while processing the report request"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Update report
Partially update a saved report. view_config is a typed, merge-only
patch: omitted supported fields, unknown compatible stored view fields,
metric_config, ownership, IDs, and permissions remain unchanged.
Send the ETag returned by GET /reports/{report_id} in If-Match
whenever view_config is present. A stale value is rejected with 412.
The legacy top-level compare_by and metadata_key fields remain
available for backward compatibility.
curl --request PATCH \
--url https://api.coval.dev/v1/reports/{report_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "Q2 plan comparison"
}
'{
"report": {
"id": "01JABCDEFGHJKMNPQRSTVWXYZ0",
"created_at": null,
"created_by": null,
"updated_by": "01J000000000000000000000002",
"name": "Agent Outcomes",
"run_ids": [],
"simulation_output_ids": [],
"source_human_review_project_id": null,
"compare_by": "metadata",
"metadata_key": "rbi_vendor",
"permissions": "PRIVATE",
"updated_at": "2026-07-29T18:24:09.654321Z",
"revision": "2026-07-29T18:24:09.654321Z",
"view_config": {
"is_monitoring": true,
"compare_by": "metadata",
"metadata_key": "rbi_vendor",
"custom_dimension_id": null,
"view_mode": "grouped",
"secondary_compare_by": "none",
"secondary_metadata_key": null,
"secondary_custom_dimension_id": null,
"custom_dimensions": [],
"monitoring_filters": {
"start_date": "2026-07-01T00:00:00.000000Z",
"end_date": "2026-08-01T00:00:00.000000Z",
"monitoring_filter": true
}
},
"metric_config": {
"01JMETRICABCDEFGHJKMNPQRS": {
"visible": true,
"passing_threshold": 0.8
}
}
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "metadata_key",
"description": "metadata_key is required when compare_by is metadata"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "x-api-key",
"description": "API key is required in the x-api-key header"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Insufficient permissions",
"details": [
{
"field": "permissions",
"description": "The API key does not include the required report permission."
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Report not found",
"details": [
{
"field": "report_id",
"description": "Report not found or not authorized."
}
]
}
}{
"error": {
"code": "FAILED_PRECONDITION",
"message": "Report revision is stale",
"details": [
{
"field": "If-Match",
"description": "Report configuration changed after it was read. Fetch the report and retry."
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred while processing the report request"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Authorizations
API key for authentication
Headers
Strong ETag from GET /reports/{report_id}. Required when the PATCH
body contains view_config; omit for legacy non-configuration updates.
Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.
1 - 26Path Parameters
Saved report ULID.
26Body
Report name, trimmed to 1–200 characters. Whitespace-only names are rejected. Omit to preserve the name; null is rejected.
1 - 200"Q2 plan comparison"
Replacement run IDs. All must belong to the authenticated organization.
1 - 2000 elements[
"8EktrIgaVxn9LfxkIynagX",
"9FltuJhbWyoAMgymJzobhY"
]
Replacement simulation IDs pinning the report to a subset of simulations. When set, this is the report's authoritative scope.
10000["AGktrIgaVxn9LfxkIynagX"]
Human review project the simulations were sourced from; simulation_output_ids
must belong to it. Omit to leave unchanged — null is rejected, the linkage
cannot be cleared via update.
26"01JABCDEFGHJKMNPQRSTVWXYZ0"
Dimension to group and compare runs by in the report view. custom groups by a
caller-defined dimension and requires custom_dimensions.
none, run, agent, mutation, persona, test_case, metadata, custom "persona"
Required when changing compare_by to metadata; otherwise omit it.
1 - 200"customer.plan"
PUBLIC creates a login-free shareable report; PRIVATE keeps it organization-only.
PUBLIC, PRIVATE "PRIVATE"
Merge-only patch for supported report view fields. Requires
If-Match; cannot be combined with the legacy top-level
compare_by or metadata_key fields.
Show child attributes
Show child attributes
Response
Report updated successfully
Show child attributes
Show child attributes
Was this page helpful?