Skip to main content
PATCH
/
reports
/
{report_id}
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",
    "name": "Plan comparison",
    "run_ids": [
      "8EktrIgaVxn9LfxkIynagX",
      "9FltuJhbWyoAMgymJzobhY"
    ],
    "compare_by": "metadata",
    "metadata_key": "customer.plan",
    "permissions": "PUBLIC"
  }
}
{
  "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": "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

​
x-api-key
string
header
required

API key for authentication

Path Parameters

​
report_id
string
required

Saved report ULID.

Required string length: 26

Body

application/json
​
name
string

Display name for the saved report.

Required string length: 1 - 200
Example:

"Q2 plan comparison"

​
run_ids
string[]

Replacement run IDs. All must belong to the authenticated organization.

Required array length: 1 - 2000 elements
Example:
[
  "8EktrIgaVxn9LfxkIynagX",
  "9FltuJhbWyoAMgymJzobhY"
]
​
simulation_output_ids
string[]

Replacement simulation IDs pinning the report to a subset of simulations. When set, this is the report's authoritative scope.

Maximum array length: 10000
Example:
["AGktrIgaVxn9LfxkIynagX"]
​
source_human_review_project_id
string

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.

Required string length: 26
Example:

"01JABCDEFGHJKMNPQRSTVWXYZ0"

​
compare_by
enum<string>
default:none

Dimension to group and compare runs by in the report view.

Available options:
none,
run,
agent,
mutation,
persona,
test_case,
metadata
Example:

"persona"

​
metadata_key
string | null

Required when changing compare_by to metadata; otherwise omit it.

Required string length: 1 - 200
Example:

"customer.plan"

​
permissions
enum<string>
default:PRIVATE

PUBLIC creates a login-free shareable report; PRIVATE keeps it organization-only.

Available options:
PUBLIC,
PRIVATE
Example:

"PRIVATE"

Response

Report updated successfully

​
report
object
required