OpenAPI Specification
openapi: 3.0.3
info:
title: Coval Agents Dashboards API
version: 1.0.0
description: '
Manage configurations for simulations and evaluations.
'
contact:
name: Coval API Support
email: support@coval.dev
url: https://docs.coval.ai
license:
name: Proprietary
url: https://coval.dev/terms
servers:
- url: https://api.coval.dev/v1
description: Production API
security:
- ApiKeyAuth: []
tags:
- name: Dashboards
description: Dashboard CRUD operations
paths:
/dashboards:
post:
operationId: createDashboard
summary: Create dashboard
description: Create a new dashboard for your organization.
tags:
- Dashboards
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDashboardRequest'
examples:
basic:
summary: Create a dashboard
value:
display_name: Production Metrics
responses:
'201':
description: Dashboard created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDashboardResponse'
examples:
created:
$ref: '#/components/examples/DashboardCreated'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
get:
operationId: listDashboards
summary: List dashboards
description: List dashboards for your organization.
tags:
- Dashboards
security:
- ApiKeyAuth: []
parameters:
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
description: Maximum number of results per page
- name: page_token
in: query
required: false
schema:
type: string
description: Opaque pagination token from previous response
- name: order_by
in: query
required: false
schema:
type: string
example: -create_time
description: Sort field and direction. Prefix with - for descending (e.g. -create_time).
responses:
'200':
description: Dashboards retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListDashboardsResponse'
examples:
success:
$ref: '#/components/examples/ListDashboardsSuccess'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/dashboards/{dashboard_id}:
get:
operationId: getDashboard
summary: Get dashboard
description: Retrieve a specific dashboard by ID.
tags:
- Dashboards
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DashboardId'
responses:
'200':
description: Dashboard retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetDashboardResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
patch:
operationId: updateDashboard
summary: Update dashboard
description: Update a dashboard.
tags:
- Dashboards
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DashboardId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDashboardRequest'
examples:
rename:
summary: Rename a dashboard
value:
display_name: Updated Dashboard Name
responses:
'200':
description: Dashboard updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDashboardResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
delete:
operationId: deleteDashboard
summary: Delete dashboard
description: Delete a dashboard.
tags:
- Dashboards
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DashboardId'
responses:
'200':
description: Dashboard deleted successfully
content:
application/json:
schema:
type: object
description: Empty response body
example: {}
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
components:
responses:
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INTERNAL
message: Internal server error
details:
- description: An unexpected error occurred
Unauthorized:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: UNAUTHENTICATED
message: Authentication failed
details:
- field: X-API-Key
description: Invalid or missing API key
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INVALID_ARGUMENT
message: Invalid request body
details:
- field: display_name
description: display_name must be between 1 and 255 characters
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: NOT_FOUND
message: Resource not found
details:
- field: dashboard_id
description: Dashboard not found or not accessible by your organization
schemas:
ListDashboardsResponse:
type: object
required:
- dashboards
properties:
dashboards:
type: array
items:
$ref: '#/components/schemas/DashboardResource'
next_page_token:
type: string
nullable: true
description: Token for fetching next page (null if no more results)
DashboardResource:
type: object
description: Dashboard resource
required:
- name
- create_time
- update_time
properties:
name:
type: string
description: Resource name in format `dashboards/{id}`
example: dashboards/abc123def456ghi789jklm
display_name:
type: string
nullable: true
maxLength: 255
description: Human-readable dashboard name
example: Production Metrics
description:
type: string
nullable: true
description: Free-text dashboard description
example: Production monitoring metrics
is_default:
type: boolean
description: Whether this is the organization's default dashboard (the one shown when no dashboard is specified)
example: true
is_favorite:
type: boolean
description: Whether the dashboard is marked as a favorite
example: false
position:
type: integer
description: Ordering position within the organization's dashboards
example: 0
config:
type: object
nullable: true
additionalProperties: true
description: Free-form JSON config blob (e.g. saved date preferences)
create_time:
type: string
format: date-time
description: Creation timestamp (ISO 8601)
example: '2025-10-14T12:00:00Z'
update_time:
type: string
format: date-time
description: Last update timestamp (ISO 8601)
example: '2025-10-15T14:30:00Z'
UpdateDashboardResponse:
type: object
required:
- dashboard
properties:
dashboard:
$ref: '#/components/schemas/DashboardResource'
UpdateDashboardRequest:
type: object
description: All fields optional (PATCH semantics). Provided fields are updated; omitted or null fields are left unchanged. Setting is_default=true unsets any other default dashboard in the organization. config fully replaces the stored blob; to clear a value send an empty string (description) or an empty object (config) rather than null.
properties:
display_name:
type: string
nullable: true
minLength: 1
maxLength: 255
description: Updated dashboard name
description:
type: string
nullable: true
maxLength: 1000
description: Updated free-text description (empty string clears it)
is_favorite:
type: boolean
nullable: true
description: Updated favorite flag
is_default:
type: boolean
nullable: true
description: Set true to make this the organization's default dashboard (unsets any other default)
position:
type: integer
nullable: true
minimum: 0
description: Updated ordering position
config:
type: object
nullable: true
additionalProperties: true
description: Replacement free-form JSON config blob (max 50000 bytes serialized)
CreateDashboardRequest:
type: object
required:
- display_name
properties:
display_name:
type: string
minLength: 1
maxLength: 255
description: Human-readable dashboard name
example: Production Metrics
description:
type: string
maxLength: 1000
description: Optional free-text description
is_favorite:
type: boolean
default: false
description: Mark the dashboard as a favorite
is_default:
type: boolean
nullable: true
description: Mark as the organization's default dashboard. Omit to auto-default the first dashboard in the organization; set true to make this the default (any existing default is unset).
position:
type: integer
minimum: 0
description: Ordering position. Omit to append to the end.
config:
type: object
additionalProperties: true
description: Free-form JSON config blob (max 50000 bytes serialized)
ErrorResponse:
type: object
description: Standard error response
required:
- error
properties:
error:
type: object
required:
- code
- message
- details
properties:
code:
type: string
description: Error code
enum:
- INVALID_ARGUMENT
- UNAUTHENTICATED
- NOT_FOUND
- INTERNAL
example: INVALID_ARGUMENT
message:
type: string
description: Human-readable error message
example: Invalid request parameter
details:
type: array
description: Detailed error information
items:
type: object
properties:
field:
type: string
nullable: true
description: Field that caused the error
description:
type: string
description: Detailed error description
CreateDashboardResponse:
type: object
required:
- dashboard
properties:
dashboard:
$ref: '#/components/schemas/DashboardResource'
GetDashboardResponse:
type: object
required:
- dashboard
properties:
dashboard:
$ref: '#/components/schemas/DashboardResource'
examples:
ListDashboardsSuccess:
summary: Successful list response
value:
dashboards:
- name: dashboards/abc123def456ghi789jklm
display_name: Production Metrics
create_time: '2025-10-14T12:00:00Z'
update_time: '2025-10-15T14:30:00Z'
- name: dashboards/xyz789abc012def345ghij
display_name: Voice Agent Quality
create_time: '2025-10-13T08:00:00Z'
update_time: '2025-10-13T08:00:00Z'
next_page_token: null
DashboardCreated:
summary: Dashboard created
value:
dashboard:
name: dashboards/abc123def456ghi789jklm
display_name: Production Metrics
create_time: '2025-10-14T12:00:00Z'
update_time: '2025-10-14T12:00:00Z'
parameters:
DashboardId:
name: dashboard_id
in: path
required: true
schema:
type: string
description: Dashboard resource ID (22-character ShortUUID)
example: abc123def456ghi789jklm
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
x-visibility: external