{
"openapi": "3.1.0",
"info": {
"title": "Lightsage Public API",
"description": "Public API for Lightsage CLI and external integrations.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.lightsage.com",
"description": "Production"
}
],
"paths": {
"/v2/status": {
"get": {
"tags": [
"Status"
],
"summary": "Get Status",
"description": "Checks API liveness without authentication. Use `GET /v2/auth/status` to validate an API key.",
"operationId": "v2_status_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v2/auth/status": {
"get": {
"tags": [
"Status"
],
"summary": "Get Auth Status",
"description": "Validates the API key and returns its organization ID, API key ID, scopes, and authentication status.",
"operationId": "v2_auth_status_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/visibility/current": {
"get": {
"tags": [
"Visibility"
],
"summary": "Retrieve Current Visibility",
"description": "Returns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company. Metrics are computed from active prompts only; when no data exists, values are `null`.",
"operationId": "v2_visibility_current_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicCurrentVisibilityResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/visibility/overview": {
"get": {
"tags": [
"Visibility"
],
"summary": "Retrieve Visibility Overview",
"description": "Returns aggregate snapshot, daily trends, per-platform breakdowns, and competitor comparison. Calculated from active prompts only.",
"operationId": "v2_visibility_overview_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicVisibilityOverviewResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/visibility/citations": {
"get": {
"tags": [
"Visibility"
],
"summary": "List Top Cited Urls",
"description": "Returns URL-level citation counts ranked from most to least cited. Results can be filtered by platform and to owned or external sources.",
"operationId": "v2_visibility_citations_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end; defaults to today."
},
{
"name": "platform",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Platform"
},
"description": "Optional answer-platform ID, name, or slug."
},
{
"name": "source_type",
"in": "query",
"required": false,
"schema": {
"enum": [
"all",
"owned",
"external"
],
"type": "string",
"default": "all",
"title": "Source Type"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 20,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicTopCitedUrlsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/visibility/prompts": {
"get": {
"tags": [
"Visibility"
],
"summary": "Retrieve Prompt Visibility Report",
"description": "Returns per-topic and per-prompt visibility metrics including recommendation score, rank, visibility score, average position, and citation counts.",
"operationId": "v2_visibility_prompts_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPromptVisibilityReportResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/prompts": {
"get": {
"tags": [
"Prompts"
],
"summary": "List Prompts",
"description": "Returns active and inactive prompts by default. Set `include_archived` to include archived prompts.",
"operationId": "v2_prompts_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "topic_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Topic Id"
},
"description": "Optional prompt topic ID."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"enum": [
"active",
"inactive",
"archived"
],
"type": "string",
"title": "Status"
}
},
{
"name": "include_archived",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Include Archived"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ListPromptsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Prompts"
],
"summary": "Create Prompts",
"description": "Creates prompts in a batch. Each item is validated independently, so the response can contain both created prompts and individual errors.",
"operationId": "v2_prompts_create",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2PromptsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptBatchResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/prompts/topics": {
"get": {
"tags": [
"Prompts"
],
"summary": "List Topics",
"description": "Returns all prompt topics available to the organization.",
"operationId": "v2_prompt_topics_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptTopicsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
},
"post": {
"tags": [
"Prompts"
],
"summary": "Create Topic",
"description": "Creates a prompt topic and returns the saved topic.",
"operationId": "v2_prompt_topics_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePromptTopicRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPromptTopic"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/prompts/topics/{topic_id}": {
"patch": {
"tags": [
"Prompts"
],
"summary": "Update Topic",
"description": "Renames a prompt topic and returns the updated topic.",
"operationId": "v2_prompt_topics_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "topic_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Topic Id"
},
"description": "Prompt topic ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePromptTopicRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPromptTopic"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Prompts"
],
"summary": "Delete Topic",
"description": "Archives a prompt topic. Set `archive_prompts` to archive remaining prompts; otherwise the request fails with `400` if prompts remain.",
"operationId": "v2_prompt_topics_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "topic_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Topic Id"
},
"description": "Prompt topic ID."
},
{
"name": "archive_prompts",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Archive Prompts"
},
"description": "Archive prompts still assigned to this topic before deleting it."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicOkResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/prompts/runs": {
"post": {
"tags": [
"Prompts"
],
"summary": "Run Prompts",
"description": "Queue saved prompts using the organization's configured targets.\n\nProvide `prompt_ids` to run selected prompts, or omit them to run all active\nprompts. Saved prompt run settings apply to coding-agent targets. The\nresponse returns a run ID to poll with\n`GET /v2/prompts/runs/{run_id}/status`.",
"operationId": "v2_prompt_runs_create",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2PromptRunRequest"
},
"examples": {
"selected_prompts": {
"summary": "Run selected prompts",
"value": {
"prompt_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
},
"all_active_prompts": {
"summary": "Run all active prompts",
"value": {
"force": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptRunJobResponse"
}
}
}
},
"400": {
"description": "No runnable configured targets were found for the selected prompts.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "No configured prompt targets were found for this organization. Configure prompt targets first."
}
}
}
},
"402": {
"description": "The organization does not currently have enough credits for the requested run.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Insufficient credits"
},
"required": {
"type": "number",
"description": "Usage-based credits the requested run needs."
},
"balance": {
"type": "number",
"description": "The organization's current credit balance."
}
},
"required": [
"error",
"required",
"balance"
]
}
},
"required": [
"detail"
]
}
}
}
},
"403": {
"description": "One or more configured targets are unavailable on the organization's current plan.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Your current plan does not include: cursor"
}
}
}
},
"503": {
"description": "The background queue is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Background queue is not available"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "prompts",
"x-speakeasy-name-override": "run"
},
"get": {
"tags": [
"Prompts"
],
"summary": "List Prompt Runs",
"description": "Returns stored prompt runs with limit-and-offset pagination, without exposing raw runtime or provider configuration. Filter by prompt, platform, or date range.",
"operationId": "v2_prompt_runs_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "prompt_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Prompt Id"
},
"description": "Optional prompt ID."
},
{
"name": "platform_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Platform Id"
},
"description": "Optional answer-platform ID."
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Start Date"
},
"description": "Inclusive start date in `YYYY-MM-DD` format."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "End Date"
},
"description": "Inclusive end date in `YYYY-MM-DD` format."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptRunsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/prompts/runs/{run_id}/status": {
"get": {
"tags": [
"Prompts"
],
"summary": "Get Prompt Run Status",
"description": "Return status and progress for a queued prompt run.\n\nPoll this endpoint until `status` is `completed`, `failed`, or `cancelled`.\nIndividual stored results are available from `GET /v2/prompts/runs`.",
"operationId": "v2_prompt_run_status_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Run Id"
},
"description": "Run ID returned by `POST /v2/prompts/runs`, not a stored prompt result ID."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptRunJobResponse"
}
}
}
},
"400": {
"description": "The prompt run ID is not a valid UUID.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Invalid ID format"
}
}
}
},
"404": {
"description": "The prompt run job does not exist or is not visible to this API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Prompt run not found"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "prompts",
"x-speakeasy-name-override": "run_status"
}
},
"/v2/prompts/runs/{run_id}": {
"get": {
"tags": [
"Prompts"
],
"summary": "Retrieve Prompt Run",
"description": "Returns one stored prompt run, including mentions, citations, and any sanitized coding-agent trace captured for the run.",
"operationId": "v2_prompt_runs_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptRunDetail"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/prompts/{prompt_id}": {
"get": {
"tags": [
"Prompts"
],
"summary": "Retrieve Prompt",
"description": "Returns a prompt with its topic, platforms, tags, lifecycle status, and coding-agent run settings.",
"operationId": "v2_prompts_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "prompt_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Prompt Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Prompts"
],
"summary": "Update Prompt",
"description": "Updates a prompt's text, topic, platforms, lifecycle status, or coding-agent run settings. Omitted fields remain unchanged.",
"operationId": "v2_prompts_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "prompt_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Prompt Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateV2PromptRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Prompts"
],
"summary": "Delete Prompt",
"description": "Archives the prompt and excludes it from normal listings while preserving its historical run data.",
"operationId": "v2_prompts_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "prompt_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Prompt Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicOkResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/opportunities": {
"get": {
"tags": [
"Opportunities"
],
"summary": "List Opportunities",
"description": "Returns ranked opportunities computed from stored prompt visibility results. Each includes an `execution_prompt` with context for an AI agent. Default window is 30 days.",
"operationId": "v2_opportunities_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "since",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Since"
},
"description": "Relative or absolute window start, such as `30d` or `2026-08-01`."
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Start Date"
},
"description": "Inclusive start date; overrides `since`."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "End Date"
},
"description": "Inclusive end date; defaults to today."
},
{
"name": "category",
"in": "query",
"required": false,
"schema": {
"enum": [
"quick_wins",
"growth",
"refresh",
"citations"
],
"type": "string",
"title": "Category"
}
},
{
"name": "opportunity_type",
"in": "query",
"required": false,
"schema": {
"enum": [
"almost_winning",
"negative_sentiment",
"lost_wins",
"competitor_gaps",
"untapped_topics",
"platform_blind_spots",
"content_gaps",
"declining_visibility",
"volatile_visibility",
"citation_gaps",
"high_citation_sources",
"listicle_targets"
],
"type": "string",
"title": "Opportunity Type"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"default": 50,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOpportunitiesResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/opportunities/{opportunity_id}": {
"get": {
"tags": [
"Opportunities"
],
"summary": "Retrieve Opportunity",
"description": "Returns one computed opportunity and its execution context for the selected date window.",
"operationId": "v2_opportunities_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "opportunity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Opportunity Id"
}
},
{
"name": "since",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Since"
},
"description": "Relative or absolute window start."
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Start Date"
},
"description": "Inclusive start date; overrides `since`."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "End Date"
},
"description": "Inclusive end date; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PromptOpportunity"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/tasks": {
"get": {
"tags": [
"Tasks"
],
"summary": "List Tasks",
"description": "Returns persisted daily tasks with execution instructions. Includes per-status counts not narrowed by the `status` filter.",
"operationId": "v2_tasks_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "action_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Action Date"
},
"description": "Optional queue date in `YYYY-MM-DD` format."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"enum": [
"active",
"todo",
"new",
"in_progress",
"completed",
"done",
"dismissed",
"all"
],
"type": "string",
"default": "active",
"title": "Status"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ListTasksResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Tasks"
],
"summary": "Create Task",
"description": "Adds a task to today's queue and returns it with its execution prompt. New tasks start as `new`.",
"operationId": "v2_tasks_create",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PublicTask"
}
}
}
},
"400": {
"description": "The assignee is not a member of your organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Assignee must be a member of your organization"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/tasks/{task_id}": {
"get": {
"tags": [
"Tasks"
],
"summary": "Retrieve Task",
"description": "Returns one persisted task and its execution prompt.",
"operationId": "v2_tasks_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Task Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PublicTask"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Tasks"
],
"summary": "Update Task",
"description": "Updates a task's status, priority, assignee, or action type. Only sent fields are changed; omitted fields remain unchanged.",
"operationId": "v2_tasks_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Task Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTaskRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2PublicTask"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/site-audits": {
"get": {
"tags": [
"Site Audits"
],
"summary": "List Site Audits",
"description": "Returns every audited page and its actionable issues. Each page includes its score, priority, issue descriptions, evidence, and recommended fixes. This reads existing data and does not start a crawl.",
"operationId": "v2_site_audits_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSiteAuditListResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/site-audits/{site_id}": {
"get": {
"tags": [
"Site Audits"
],
"summary": "Retrieve Site Audit",
"description": "Returns one audited page with its score, priority, supporting evidence, and recommended fixes.",
"operationId": "v2_site_audits_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSiteAuditPage"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/agent-analytics/sites": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "List Agent Analytics Sites",
"description": "Returns every site with tracked visits. Use a `site_id` from this list to read that site's agent traffic.",
"operationId": "v2_agent_analytics_sites_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsSiteListResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/agent-analytics/sites/{site_id}/summary": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "Retrieve Agent Analytics Summary",
"description": "Returns a site's visits by traffic type (coding agents, user-requested AI fetches, AI search, AI training, other bots, and people) for the date range and for the same number of days before it.",
"operationId": "v2_agent_analytics_summary_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 6 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end in UTC; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsSummary"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/agent-analytics/sites/{site_id}/sources": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "List Agent Analytics Sources",
"description": "Returns every coding agent and bot that visited a site in the date range, with its traffic type and visit count, most visits first. Human visits are one `people` row.",
"operationId": "v2_agent_analytics_sources_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 6 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end in UTC; defaults to today."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsSourceListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/agent-analytics/sites/{site_id}/pages": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "List Agent Analytics Pages",
"description": "Returns the pages AI agents and bots read on a site in the date range, with visits per traffic type. Sorted by AI visits unless `sort` is set. With `type`, returns only pages that traffic type visited. With `agent`, returns only the pages that one coding agent read.",
"operationId": "v2_agent_analytics_pages_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 6 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end in UTC; defaults to today."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"default": 20,
"title": "Limit"
}
},
{
"name": "search",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 200,
"title": "Search"
},
"description": "Only pages whose path contains this text."
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"enum": [
"coding",
"user",
"search",
"training",
"other",
"people",
"ai_total",
"last_seen"
],
"type": "string",
"default": "ai_total",
"title": "Sort"
},
"description": "Traffic type to sort by, most visits first, or `last_seen` for the latest visit first."
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"enum": [
"coding",
"user",
"search",
"training",
"other",
"people"
],
"type": "string",
"title": "Type"
},
"description": "Only pages this traffic type visited."
},
{
"name": "agent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 100,
"title": "Agent"
},
"description": "Only pages this coding agent read, by the `name` the sources list gives it, such as `codex` or `cursor`."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsPageListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/agent-analytics/sites/{site_id}/error-pages": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "List Agent Analytics Error Pages",
"description": "Returns the pages on a site that returned an error status (400 and up) in the date range, most error requests first, with the agents, bots, and people that got each error. Set `status` to 404 for pages that were not found. Needs server-side tracking that records status codes; `status_codes_tracked` says whether the site has any.",
"operationId": "v2_agent_analytics_error_pages_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 6 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end in UTC; defaults to today."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"default": 50,
"title": "Limit"
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 599,
"minimum": 400,
"title": "Status"
},
"description": "Only this status code, such as 404."
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"enum": [
"coding",
"user",
"search",
"training",
"other",
"people"
],
"type": "string",
"title": "Type"
},
"description": "Only errors this traffic type got."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsErrorPageListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/agent-analytics/sites/{site_id}/countries": {
"get": {
"tags": [
"Agent Analytics"
],
"summary": "List Agent Analytics Countries",
"description": "Returns a site's visits from coding agents and AI assistants per country in the date range, most visits first.",
"operationId": "v2_agent_analytics_countries_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "site_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Site Id"
}
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"description": "Inclusive range start; defaults to 6 days before the end date. The range may span at most 90 days."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date",
"title": "End Date"
},
"description": "Inclusive range end in UTC; defaults to today."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 20,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAgentAnalyticsCountryListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/evals": {
"get": {
"tags": [
"Evals"
],
"summary": "List Evals",
"description": "Returns all active eval definitions owned by the organization. Agent Preference evals are not included; list them with `GET /v2/agent-preference/evals`.",
"operationId": "v2_evals_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
},
"post": {
"tags": [
"Evals"
],
"summary": "Create Eval",
"description": "Creates a reusable simulation definition with one or more task prompts and judges. Optional agents, persona, CLI installations, MCP servers, setup commands, cleanup commands, grounding policy, repeat count, and tags are saved with the eval. `search_grounding` supports `disabled`, `enabled`, and `default`; `default` preserves normal platform behavior. Creating the eval does not start a run and does not accept secret environment values.",
"operationId": "v2_evals_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2EvalRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Eval"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/evals/batch": {
"post": {
"tags": [
"Evals"
],
"summary": "Create evals from a template",
"description": "Step 2 of the reusable template workflow. Provide the `id` and `version` returned by `POST /v2/eval-templates` as `template_id` and `expected_template_version`, then provide only prompt-specific fields in `evals`. The template supplies only the settings named in its `included_components`; omitted settings keep the values supplied by the creation workflow or its defaults. Included values are copied at creation time, so later template changes do not alter the created evals. Competitor selections create one additional eval per selected competitor for every input item, and the response groups each base eval with those variants. Brand-scoped runtime resources are validated against the organization's primary brand before any eval is created.",
"operationId": "v2_evals_batch_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEvalTemplateBatchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplateBatchResponse"
}
}
}
},
"400": {
"description": "The template contains invalid judges, targets, scheduling, metadata, or organization resources.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string"
}
},
"type": "object",
"required": [
"detail"
]
},
"example": {
"detail": "Unknown or inactive competitor ID"
}
}
}
},
"404": {
"description": "The Eval template does not exist in the organization.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string"
}
},
"type": "object",
"required": [
"detail"
]
},
"example": {
"detail": "Eval template not found"
}
}
}
},
"409": {
"description": "The supplied template version is stale.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string"
}
},
"type": "object",
"required": [
"detail"
]
},
"example": {
"detail": "The Eval template changed after it was loaded. Refresh and try again."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/evals/{eval_id}": {
"get": {
"tags": [
"Evals"
],
"summary": "Retrieve Eval",
"description": "Returns one reusable eval simulation definition.",
"operationId": "v2_evals_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Eval"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Evals"
],
"summary": "Update Eval",
"description": "Updates a reusable eval simulation definition. Omitted fields remain unchanged. Empty `agent`, `clis`, `mcps`, `setup_commands`, `cleanup_commands`, or `tags` arrays clear those collections, and `persona: null` clears the saved persona.",
"operationId": "v2_evals_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateV2EvalRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Eval"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Evals"
],
"summary": "Delete Eval",
"description": "Permanently deletes an eval and all of its saved configurations.",
"operationId": "v2_evals_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Eval"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/evals/{eval_id}/configurations": {
"get": {
"tags": [
"Evals"
],
"summary": "List Configurations",
"description": "Returns the saved runtime configurations for an eval, including repository, environment, and tool selections.",
"operationId": "v2_eval_configurations_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalConfigurationsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Evals"
],
"summary": "Create Configuration",
"description": "Creates a saved runtime configuration that pairs an eval with a repository, environment, and selected tools.",
"operationId": "v2_eval_configurations_create",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2EvalConfigurationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalConfiguration"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/evals/{eval_id}/configurations/{configuration_id}": {
"get": {
"tags": [
"Evals"
],
"summary": "Retrieve Configuration",
"description": "Returns one saved configuration for an eval.",
"operationId": "v2_eval_configurations_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
},
{
"name": "configuration_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Configuration Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalConfiguration"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Evals"
],
"summary": "Update Configuration",
"description": "Updates an eval configuration; omitted fields remain unchanged.",
"operationId": "v2_eval_configurations_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
},
{
"name": "configuration_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Configuration Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateV2EvalConfigurationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalConfiguration"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Evals"
],
"summary": "Delete Configuration",
"description": "Permanently deletes an eval configuration and returns its last saved state.",
"operationId": "v2_eval_configurations_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
},
{
"name": "configuration_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Configuration Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalConfiguration"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/eval-templates": {
"get": {
"tags": [
"Eval Templates"
],
"summary": "List Eval templates",
"description": "Returns active reusable Eval templates owned by the authenticated organization. Templates contain reusable configuration and never task prompts.",
"operationId": "v2_eval_templates_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplatesResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
},
"post": {
"tags": [
"Eval Templates"
],
"summary": "Create an Eval template",
"description": "Step 1 of the reusable template workflow. Creates an organization-owned Eval template containing only the configuration components selected in `included_components`. Do not include task prompts in the template. The response returns the template `id` and `version`; pass them as `template_id` and `expected_template_version` to `POST /v2/evals/batch` with each eval's name and prompts. Applying a template copies its values into the new evals without creating a live link.",
"operationId": "v2_eval_templates_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEvalTemplateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplate"
}
}
}
},
"400": {
"description": "The template contains invalid judges, targets, scheduling, metadata, or organization resources.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string"
}
},
"type": "object",
"required": [
"detail"
]
},
"example": {
"detail": "Unknown or inactive competitor ID"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/eval-templates/{template_id}": {
"get": {
"tags": [
"Eval Templates"
],
"summary": "Retrieve an Eval template",
"description": "Returns one active reusable Eval template.",
"operationId": "v2_eval_templates_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Template Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplate"
}
}
}
},
"404": {
"description": "The Eval template does not exist in the organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval template not found"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Eval Templates"
],
"summary": "Update an Eval template",
"description": "Updates an Eval template. Supply `expected_template_version` to reject an edit based on stale data. Existing evals are never changed.",
"operationId": "v2_eval_templates_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Template Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEvalTemplateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplate"
}
}
}
},
"400": {
"description": "The template contains invalid judges, targets, scheduling, metadata, or organization resources.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Unknown or inactive competitor ID"
}
}
}
},
"404": {
"description": "The Eval template does not exist in the organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval template not found"
}
}
}
},
"409": {
"description": "The supplied template version is stale.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "The Eval template changed after it was loaded. Refresh and try again."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Eval Templates"
],
"summary": "Delete an Eval template",
"description": "Soft-deletes an Eval template. Evals previously created from it remain independent and continue to run with their copied configuration.",
"operationId": "v2_eval_templates_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Template Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EvalTemplate"
}
}
}
},
"404": {
"description": "The Eval template does not exist in the organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval template not found"
}
}
}
},
"409": {
"description": "The supplied template version is stale.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "The Eval template changed after it was loaded. Refresh and try again."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/eval-runs": {
"get": {
"tags": [
"Eval Runs"
],
"summary": "List Runs",
"description": "Returns custom eval runs, ordered newest first, with lifecycle state and progress. Includes scheduled, onboarding, and pull request runs and runs started in the Lightsage app, as well as runs started through `POST /v2/eval-runs`.",
"operationId": "v2_eval_runs_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalRunsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Eval Runs"
],
"summary": "Start an eval run",
"description": "Queues a durable eval job and returns immediately with a polling ID. Poll `GET /v2/eval-runs/{run_id}` until its status reaches a terminal value; once finished it also returns the results and analysis. Follow a run live with the monitor operation.\n\nSend one of these flat request forms:\n\n- **Saved eval:** provide `eval_id`; optionally replace its prompts, persona, agents, CLIs, MCPs, setup commands, cleanup commands, or runs for this launch. A saved configuration can still provide repository, environment, skills, and legacy tool selections.\n- **Direct create-and-run:** provide `prompts`, `judges`, and `agent`. You may also provide a persona, tags, repository, write-only environment variables, saved or inline CLIs and MCP servers, skills, setup commands, and cleanup commands.\n\nThe run fans out across prompts \u00d7 agents \u00d7 runs. Persona is shared metadata and does not multiply attempts. No separate `mode` field is required. If the organization lacks the estimated credits, the request fails with `402` before dispatching work.\n\nA saved or inline environment containing an empty or placeholder credential is rejected with `400` before any evaluation is dispatched.",
"operationId": "v2_eval_runs_create",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2EvalRunRequest"
},
"examples": {
"saved_eval": {
"summary": "Run a self-contained saved eval",
"description": "Provide `eval_id` and any environment values required by its saved MCP definitions. A configuration remains optional.",
"value": {
"eval_id": "eval_123",
"env": {
"LIGHTSAGE_API_KEY": "secret-value"
}
}
},
"direct_eval": {
"summary": "Create and run an eval directly",
"description": "Omit `eval_id` and provide `prompts`, `judges`, and one or more values in `agent`. The created eval ID is returned with the run.",
"value": {
"agent": [
"codex:gpt-5-4",
"claude-code:claude-opus-4-8"
],
"prompts": [
"Complete the task with the CLI.",
"Complete the task with the MCP server."
],
"judges": [
"The requested workflow succeeds.",
"The generated project passes its tests."
],
"persona": "Platform engineer",
"runs": 2,
"tags": [
"sdk",
"smoke-test"
],
"repository": "nextjs-starter",
"clis": [
"brew install lightsagehq/tools/lightsage",
"npx -y firecrawl-cli@latest init --all"
],
"setup_commands": [
"npm install",
"npm run db:migrate"
],
"cleanup_commands": [
"npm run db:cleanup"
],
"mcps": [
{
"name": "lightsage",
"type": "http",
"url": "https://mcp.lightsage.com/mcp",
"headers": {
"X-Lightsage-Api-Key": "${LIGHTSAGE_API_KEY}"
}
}
],
"env": {
"LIGHTSAGE_API_KEY": "secret-value"
},
"skills": [
"resend/resend-skills"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalRun"
}
}
}
},
"400": {
"description": "The saved/direct mode fields, referenced resource, or environment credentials are invalid.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"examples": {
"invalid_environment_credentials": {
"summary": "Environment credentials are missing",
"value": {
"detail": "Environment profile 'Production' contains empty or placeholder values for: ACME_API_KEY. Update those values before running the evaluation."
}
}
}
}
}
},
"402": {
"description": "The organization does not currently have enough credits for the requested run.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Insufficient credits"
},
"required": {
"type": "number",
"description": "Usage-based credits the requested run needs."
},
"balance": {
"type": "number",
"description": "The organization's current credit balance."
}
},
"required": [
"error",
"required",
"balance"
]
}
},
"required": [
"detail"
]
}
}
}
},
"403": {
"description": "The requested coding agent is unavailable on the organization's current plan.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Your current plan does not include: cursor"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "evals",
"x-speakeasy-name-override": "run"
}
},
"/v2/eval-runs/{run_id}/cancel": {
"post": {
"tags": [
"Eval Runs"
],
"summary": "Cancel an eval run",
"description": "Marks an active eval run as cancelled and prevents queued attempts from starting. Running sandbox attempts are stopped asynchronously. Requests already sent to an external provider cannot be recalled, but any later response does not change the run from cancelled. Repeating this request for an already-cancelled run is safe.",
"operationId": "v2_eval_runs_cancel",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalRun"
}
}
}
},
"404": {
"description": "Eval run not found. Use the run ID returned when you started the eval.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval run not found. Use the run ID returned when you started the eval."
}
}
}
},
"409": {
"description": "The eval run has already completed or failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval run cannot be cancelled after it has completed or failed."
}
}
}
},
"503": {
"description": "Eval run cancellation is temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval run cancellation is temporarily unavailable. Try again."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "evals",
"x-speakeasy-name-override": "cancel"
}
},
"/v2/eval-runs/monitor": {
"get": {
"tags": [
"Eval Runs"
],
"summary": "Monitor Runs",
"description": "Streams an immediate snapshot followed by live status and sanitized activity. Provide `run_id` to monitor one eval run, or omit it to capture all active runs when the connection opens.",
"operationId": "v2_eval_runs_monitor",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"title": "Run Id"
},
"description": "Parent run ID returned by `POST /v2/eval-runs`. Omit to capture all currently active eval runs."
},
{
"name": "detail",
"in": "query",
"required": false,
"schema": {
"enum": [
"summary",
"verbose"
],
"type": "string",
"default": "summary",
"title": "Detail"
},
"description": "Reduced activity or the full sanitized durable trace."
},
{
"name": "after_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "After Id"
},
"description": "Durable child-event cursor used when reconnecting."
}
],
"responses": {
"200": {
"description": "A server-sent event stream of eval-run status and activity.",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
},
"examples": {
"one_run_summary": {
"summary": "Monitor one run with reduced activity",
"value": "event: snapshot\ndata: {\"runs\":[{\"run_id\":\"run_123\",\"status\":\"running\",\"progress\":{\"completed\":6,\"total\":10,\"percent\":60}}]}\n\n"
},
"one_run_verbose": {
"summary": "Monitor one run with its sanitized trace",
"value": "id: 4812\nevent: trace\ndata: {\"run_id\":\"run_123\",\"child_job_id\":\"job_123\",\"event_id\":4812,\"category\":\"tools\",\"type\":\"tool_call\",\"message\":\"Running npm test\",\"data\":{}}\n\n"
},
"all_runs_summary": {
"summary": "Monitor all currently active eval runs",
"value": "event: snapshot\ndata: {\"runs\":[{\"run_id\":\"run_123\",\"status\":\"running\"},{\"run_id\":\"run_456\",\"status\":\"pending\"}]}\n\n"
}
}
}
}
},
"404": {
"description": "Eval run not found. Use the run ID returned when you started the eval."
},
"409": {
"description": "Too many active eval runs were selected. Pass `run_id` to monitor one run, or wait for active runs to finish."
},
"503": {
"description": "Eval monitoring is temporarily unavailable. Retry after a short delay."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "evals",
"x-speakeasy-name-override": "monitor",
"x-lightsage-exclude-targets": [
"mcp"
]
}
},
"/v2/eval-runs/{run_id}/trace": {
"get": {
"tags": [
"Eval Runs"
],
"summary": "Retrieve an eval run trace",
"description": "Returns a finite page of sanitized execution events for one eval run. Use `next_after_id` as `after_id` to retrieve the next page. Use the monitor operation instead when following a run live.",
"operationId": "v2_eval_runs_trace",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Run Id"
}
},
{
"name": "after_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "After Id"
},
"description": "Return events with IDs greater than this cursor."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"default": 500,
"title": "Limit"
},
"description": "Maximum number of trace events to return."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalRunTraceResponse"
}
}
}
},
"404": {
"description": "Eval run not found. Use the run ID returned when you started the eval.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval run not found. Use the run ID returned when you started the eval."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "evals",
"x-speakeasy-name-override": "trace"
}
},
"/v2/eval-runs/{run_id}": {
"get": {
"tags": [
"Eval Runs"
],
"summary": "Retrieve an eval run",
"description": "Returns the run's current status and progress. Once its attempts finish, the response also includes their results and analysis. Poll this until the status reaches a terminal value. Use the trace operation for the raw execution event log, or the monitor operation to follow a run live.",
"operationId": "v2_eval_runs_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EvalRunDetail"
}
}
}
},
"404": {
"description": "Eval run not found. Use the run ID returned when you started the eval.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"required": [
"detail"
]
},
"example": {
"detail": "Eval run not found. Use the run ID returned when you started the eval."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "evals",
"x-speakeasy-name-override": "get"
}
},
"/v2/agent-preference/competitors": {
"get": {
"tags": [
"Agent Preference"
],
"summary": "List Competitors",
"description": "Returns the tracked competitors your company can be compared against. Use a returned `id` as `competitor_id` when creating an Agent Preference eval.",
"operationId": "v2_agent_preference_competitors_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceCompetitorsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
],
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "competitors_list"
}
},
"/v2/agent-preference/head-to-head": {
"get": {
"tags": [
"Agent Preference"
],
"summary": "Retrieve Head To Head",
"description": "Returns how often agents recommended your company over each tracked competitor: wins, losses, ties, and win rate per competitor plus a combined record. Calculated from the most recent attempts across all Agent Preference evals, up to `limit`; `truncated` reports whether older attempts were left out.",
"operationId": "v2_agent_preference_head_to_head_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"default": 500,
"title": "Limit"
},
"description": "Most recent attempts to include in the records."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceHeadToHeadResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "head_to_head_retrieve"
}
},
"/v2/agent-preference/evals": {
"get": {
"tags": [
"Agent Preference"
],
"summary": "List Evals",
"description": "Returns all active Agent Preference evals owned by the organization.",
"operationId": "v2_agent_preference_evals_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceEvalsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
],
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_list"
},
"post": {
"tags": [
"Agent Preference"
],
"summary": "Create Eval",
"description": "Creates a head-to-head comparison between your company and one tracked competitor. Each prompt asks an agent to choose, and a fixed judge records which company it recommended. Creating the eval does not start a run; pass the returned `id` as `eval_id` to `POST /v2/eval-runs`.",
"operationId": "v2_agent_preference_evals_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2AgentPreferenceEvalRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceEval"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
],
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_create"
}
},
"/v2/agent-preference/evals/{eval_id}": {
"get": {
"tags": [
"Agent Preference"
],
"summary": "Retrieve Eval",
"description": "Returns one Agent Preference eval.",
"operationId": "v2_agent_preference_evals_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceEval"
}
}
}
},
"404": {
"description": "The eval is not an Agent Preference eval in this organization.",
"content": {
"application/json": {
"example": {
"detail": "Agent preference eval not found. Use an eval ID from the agent preference evals list."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_retrieve"
},
"patch": {
"tags": [
"Agent Preference"
],
"summary": "Update Eval",
"description": "Updates an Agent Preference eval. Omitted fields remain unchanged, an empty `agent` or `tags` array clears that collection, and `persona: null` clears the saved persona. The competitor and the judge that decides the comparison cannot be changed.",
"operationId": "v2_agent_preference_evals_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateV2AgentPreferenceEvalRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceEval"
}
}
}
},
"404": {
"description": "The eval is not an Agent Preference eval in this organization.",
"content": {
"application/json": {
"example": {
"detail": "Agent preference eval not found. Use an eval ID from the agent preference evals list."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_update"
},
"delete": {
"tags": [
"Agent Preference"
],
"summary": "Delete Eval",
"description": "Permanently deletes an Agent Preference eval and returns its last saved state.",
"operationId": "v2_agent_preference_evals_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceEval"
}
}
}
},
"404": {
"description": "The eval is not an Agent Preference eval in this organization.",
"content": {
"application/json": {
"example": {
"detail": "Agent preference eval not found. Use an eval ID from the agent preference evals list."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_delete"
}
},
"/v2/agent-preference/evals/{eval_id}/results": {
"get": {
"tags": [
"Agent Preference"
],
"summary": "List Results",
"description": "Returns recorded attempts for an Agent Preference eval, newest first, each with whether your company won, lost, or tied against the competitor.",
"operationId": "v2_agent_preference_results_list",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "eval_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Eval Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"default": 50,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentPreferenceResultsResponse"
}
}
}
},
"404": {
"description": "The eval is not an Agent Preference eval in this organization.",
"content": {
"application/json": {
"example": {
"detail": "Agent preference eval not found. Use an eval ID from the agent preference evals list."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"x-speakeasy-group": "agent_preference",
"x-speakeasy-name-override": "evals_results_list"
}
},
"/v2/agents": {
"get": {
"tags": [
"Agents"
],
"summary": "List Agents",
"description": "Returns the harness-and-model combinations your plan can run, as single agent IDs for use in eval runs.",
"operationId": "v2_agents_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2AgentsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/repositories": {
"get": {
"tags": [
"Repositories"
],
"summary": "List Repositories",
"description": "Returns built-in templates and enabled saved Git repositories. Pass an item's `id` directly as `repository` in a direct eval run. Public GitHub URLs are also accepted by eval runs but are not included in this list.",
"operationId": "v2_repositories_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2RepositoriesResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
},
"post": {
"tags": [
"Repositories"
],
"summary": "Create Repository",
"description": "Adds a reusable Git repository workspace for eval configurations.",
"operationId": "v2_repositories_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateV2RepositoryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Repository"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/repositories/{repository_id}": {
"get": {
"tags": [
"Repositories"
],
"summary": "Retrieve Repository",
"description": "Returns one reusable repository workspace.",
"operationId": "v2_repositories_retrieve",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "repository_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Repository Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Repository"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Repositories"
],
"summary": "Update Repository",
"description": "Updates a repository workspace; omitted fields remain unchanged.",
"operationId": "v2_repositories_update",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "repository_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Repository Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateV2RepositoryRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Repository"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Repositories"
],
"summary": "Delete Repository",
"description": "Permanently deletes a repository workspace and returns its last saved state.",
"operationId": "v2_repositories_delete",
"security": [
{
"LightsageApiKeyAuth": []
}
],
"parameters": [
{
"name": "repository_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Repository Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Repository"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v2/environments": {
"get": {
"tags": [
"Environments"
],
"summary": "List Environments",
"description": "Returns reusable environments without exposing secret values.",
"operationId": "v2_environments_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2EnvironmentsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/mcp-servers": {
"get": {
"tags": [
"MCP Servers"
],
"summary": "List Mcp Servers",
"description": "Returns reusable MCP servers without exposing credentials or secret values.",
"operationId": "v2_mcp_servers_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2McpServersResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/clis": {
"get": {
"tags": [
"CLIs"
],
"summary": "List Clis",
"description": "Returns reusable CLIs without exposing setup or installation commands.",
"operationId": "v2_clis_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ClisResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
},
"/v2/skills": {
"get": {
"tags": [
"Skills"
],
"summary": "List Skills",
"description": "Returns reusable skills available to workflows and eval configurations.",
"operationId": "v2_skills_list",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2SkillsResponse"
}
}
}
}
},
"security": [
{
"LightsageApiKeyAuth": []
}
]
}
}
},
"components": {
"schemas": {
"CreateEvalTemplateBatchRequest": {
"properties": {
"template_id": {
"type": "string",
"minLength": 1,
"title": "Template Id",
"description": "Template `id` returned by `POST /v2/eval-templates`."
},
"expected_template_version": {
"type": "integer",
"minimum": 1.0,
"title": "Expected Template Version",
"description": "Template `version` returned when the template was read or created. When supplied, creation fails if the template changed before reuse."
},
"evals": {
"items": {
"$ref": "#/components/schemas/EvalTemplateBatchItem"
},
"type": "array",
"maxItems": 100,
"minItems": 1,
"title": "Evals",
"description": "Prompt-specific evals to create from the referenced template. Template-owned fields are intentionally rejected here to avoid ambiguous overrides."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"template_id",
"evals"
],
"title": "CreateEvalTemplateBatchRequest",
"description": "Reuse one template across up to 100 prompt-specific eval definitions.",
"examples": [
{
"evals": [
{
"name": "BTC price fetcher",
"prompts": [
"Write a Python script that prints the current price of BTC using a free API without a key."
],
"type": "workflow"
},
{
"name": "BTC alert",
"prompts": [
"Build a free BTC price alert without an API key."
],
"type": "workflow"
}
],
"expected_template_version": 1,
"template_id": "58f3604e-d58e-4eb8-b1fe-3478be875c36"
}
]
},
"CreateEvalTemplateRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name",
"description": "Organization-visible name for this reusable template."
},
"description": {
"type": "string",
"maxLength": 1000,
"title": "Description",
"description": "Optional guidance describing when to use the template."
},
"prompt": {
"type": "string",
"maxLength": 20000,
"title": "Prompt",
"description": "Prompt filled into the new eval form when the template is applied, or the scenario for Agent Preference, where `{{competitor_name}}` names the brand each comparison is against. Requests that create evals from a template still supply their own prompts."
},
"eval_type": {
"type": "string",
"enum": [
"custom_eval",
"agent_preference"
],
"title": "Eval Type",
"description": "Kind of eval the template creates. A template only applies to evals of the same type.",
"default": "custom_eval"
},
"included_components": {
"items": {
"type": "string",
"enum": [
"judges",
"targets",
"persona",
"competitors",
"tag",
"category",
"runs",
"schedule",
"repository",
"environment",
"search_grounding",
"skills",
"mcp_servers",
"clis",
"brand_docs",
"github_pr",
"runtime_commands"
]
},
"type": "array",
"minItems": 1,
"title": "Included Components",
"description": "Settings copied when the template is applied. Omitted components do not override the new eval; included components copy their saved value, including an empty value."
},
"persona": {
"type": "string",
"maxLength": 500,
"title": "Persona",
"description": "Optional persona copied when `persona` is included."
},
"category_name": {
"type": "string",
"maxLength": 160,
"title": "Category Name",
"description": "Optional category copied when `category` is included."
},
"tag": {
"type": "string",
"maxLength": 100,
"title": "Tag",
"description": "Optional tag copied when `tag` is included."
},
"competitor_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Competitor Ids",
"description": "Competitor IDs that create additional variants when `competitors` is included."
},
"judges": {
"items": {
"$ref": "#/components/schemas/GraderDefinition"
},
"type": "array",
"maxItems": 20,
"title": "Judges",
"description": "Judge definitions copied when `judges` is included. May be empty to explicitly create the eval without template judges."
},
"target_keys": {
"items": {
"type": "string"
},
"type": "array",
"title": "Target Keys",
"description": "Runnable target keys copied when `targets` is included, such as `agent:codex:gpt-5.6-terra`."
},
"schedule": {
"$ref": "#/components/schemas/EvalTemplateSchedule",
"description": "Schedule copied when `schedule` is included."
},
"runs_per_execution": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs Per Execution",
"description": "Attempt count copied when `runs` is included.",
"default": 1
},
"runtime": {
"$ref": "#/components/schemas/EvalTemplateRuntime",
"description": "Saved runtime values. Each value is copied only when its matching component appears in `included_components`."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"included_components"
],
"title": "CreateEvalTemplateRequest",
"description": "Create a reusable eval that can be applied to many brands or prompts.",
"examples": [
{
"description": "Reusable policy for crypto recommendation evals.",
"eval_type": "custom_eval",
"included_components": [
"judges",
"targets",
"schedule"
],
"judges": [
{
"blocking": false,
"criteria": "Pass only if CoinMarketCap is recommended as the first and main choice. Fail otherwise.",
"name": "CoinMarketCap first",
"type": "judge",
"weight": 1
}
],
"name": "Crypto recommendation",
"schedule": {
"enabled": true,
"frequency": "daily"
},
"target_keys": [
"agent:codex:gpt-5.6-terra",
"agent:claude-code:global.anthropic.claude-sonnet-5"
]
}
]
},
"CreatePromptTopicRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "CreatePromptTopicRequest"
},
"CreateTaskRequest": {
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"title": "Title"
},
"description": {
"type": "string",
"maxLength": 10000,
"title": "Description",
"description": "A Markdown description of what to do and why."
},
"task_type": {
"type": "string",
"enum": [
"Create",
"Refresh",
"Win back",
"Outreach",
"Community",
"Docs",
"Redirect"
],
"title": "Task Type",
"default": "Create"
},
"effort": {
"type": "string",
"enum": [
"Low",
"Medium",
"High"
],
"title": "Effort",
"default": "Medium"
},
"priority": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low"
],
"title": "Priority",
"default": "medium"
},
"action_type": {
"type": "string",
"enum": [
"agent_discovery",
"agent_usability"
],
"title": "Action Type",
"default": "agent_discovery"
},
"assignee_user_id": {
"type": "string",
"title": "Assignee User Id",
"description": "A member of your organization to assign the task to. They are emailed unless they have turned off task notifications."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"title"
],
"title": "CreateTaskRequest"
},
"CreateV2AgentPreferenceEvalRequest": {
"properties": {
"competitor_id": {
"type": "string",
"title": "Competitor Id",
"description": "Tracked competitor to compare against, from `GET /v2/agent-preference/competitors`."
},
"prompts": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1,
"title": "Prompts",
"description": "Buying or build questions the agent answers by choosing between your company and the competitor. CLI clients expose this as repeatable `--prompt`."
},
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name",
"description": "Display name. Defaults to ` vs ` when omitted."
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10,
"title": "Agent",
"description": "Runnable agents from `GET /v2/agents`. An empty array saves the comparison without default agents. CLI clients expose repeatable `--agent`."
},
"persona": {
"type": "string",
"maxLength": 160,
"title": "Persona",
"description": "Optional perspective applied to the whole comparison."
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Web-retrieval policy for every run: disabled, enabled, or default.",
"default": "default"
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs",
"description": "Independent attempts for every prompt-agent pair.",
"default": 1
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Tags"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"competitor_id",
"prompts"
],
"title": "CreateV2AgentPreferenceEvalRequest",
"examples": [
{
"agent": [
"codex:gpt-5-4"
],
"competitor_id": "8f6f3a52-6f0d-4a4b-9f3e-0c1f4a7f2b11",
"prompts": [
"Which web search API should I use for a research agent?"
],
"runs": 3,
"tags": [
"search"
]
}
]
},
"CreateV2EvalConfigurationRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"repository_id": {
"type": "string",
"title": "Repository Id"
},
"environment_id": {
"type": "string",
"title": "Environment Id"
},
"mcp_server_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mcp Server Ids"
},
"cli_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Cli Ids"
},
"skill_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Skill Ids"
},
"skills": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Skills",
"description": "Public skill packages saved with this configuration, using GitHub `owner/repository` references such as `resend/resend-skills`."
},
"include_docs": {
"type": "boolean",
"title": "Include Docs",
"default": false
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Web-retrieval policy for runs launched with this configuration.",
"default": "default"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name"
],
"title": "CreateV2EvalConfigurationRequest"
},
"CreateV2EvalRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"prompts": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1,
"title": "Prompts",
"description": "Task prompts. CLI clients expose this as repeatable `--prompt`."
},
"judges": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1,
"title": "Judges",
"description": "Plain-text success criteria. CLI clients expose this as repeatable `--judge`."
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10,
"title": "Agent",
"description": "Runnable agents from `GET /v2/agents`. An empty array saves the eval without default agents. CLI clients expose repeatable `--agent`."
},
"persona": {
"type": "string",
"maxLength": 160,
"title": "Persona",
"description": "Optional perspective applied to the whole eval. It is stored as metadata and does not change prompts or multiply attempts."
},
"clis": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Clis",
"description": "Saved CLI IDs or shell installation commands. UUID values resolve saved CLIs from `GET /v2/clis`; every other value is run as an installation command. CLI clients expose repeatable `--cli`."
},
"mcps": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/V2SavedMcpReference"
},
{
"$ref": "#/components/schemas/V2InlineMcpDefinition"
}
]
},
"type": "array",
"maxItems": 20,
"title": "Mcps",
"description": "Saved MCP references or inline portable MCP definitions."
},
"setup_commands": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Setup Commands",
"description": "Shell commands run sequentially in the prepared repository before the agent starts. CLI clients expose repeatable `--setup-command`."
},
"cleanup_commands": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Cleanup Commands",
"description": "Best-effort shell commands run sequentially after agent execution and result capture, before sandbox deletion. CLI clients expose repeatable `--cleanup-command`."
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Web-retrieval policy for every run. `disabled` hides native search and fetch tools and requests network isolation; `enabled` exposes retrieval tools, requires live retrieval in the runtime prompt, and qualifies the run only when retrieval is observed; `default` exposes the platform's normal tools without requiring retrieval.",
"default": "default"
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs",
"description": "Independent attempts for every prompt-agent pair.",
"default": 1
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Tags",
"description": "Optional labels for organizing the eval. CLI clients may expose this string array as a repeatable `--tag` flag."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"prompts",
"judges"
],
"title": "CreateV2EvalRequest",
"examples": [
{
"agent": [
"codex:gpt-5-4"
],
"cleanup_commands": [
"npm run db:cleanup"
],
"clis": [
"brew install lightsagehq/tools/lightsage"
],
"judges": [
"The SDK is installed and the request succeeds."
],
"name": "SDK installation",
"prompts": [
"Install the SDK and send a successful request."
],
"runs": 2,
"search_grounding": "disabled",
"setup_commands": [
"npm install",
"npm run db:migrate"
],
"tags": [
"sdk",
"installation"
]
}
]
},
"CreateV2EvalRunRequest": {
"properties": {
"eval_id": {
"type": "string",
"minLength": 1,
"title": "Eval Id",
"description": "Saved-run form only. Existing eval definition to run. Omit this field to use the direct create-and-run form."
},
"configuration_id": {
"type": "string",
"minLength": 1,
"title": "Configuration Id",
"description": "Saved-run form only. Optional saved repository, environment, skills, and legacy tool configuration."
},
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name",
"description": "Direct create-and-run form only. Display name for the durable eval. Defaults to the first prompt."
},
"prompts": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Prompts",
"description": "Task prompts. Required in direct mode; in saved mode, replaces saved prompts for this launch. CLI clients expose repeatable `--prompt`."
},
"judges": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Judges",
"description": "Success criteria. Required in direct mode; in saved mode, replaces saved judges for this launch. CLI clients expose repeatable `--judge`."
},
"agent": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Agent",
"description": "Runnable agents from `GET /v2/agents`. Required unless the saved eval already has agents. CLI clients expose repeatable `--agent`."
},
"persona": {
"type": "string",
"maxLength": 160,
"title": "Persona",
"description": "Optional perspective for every attempt in this launch. It does not modify prompts or add a fan-out dimension."
},
"clis": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Clis",
"description": "Saved CLI IDs or shell installation commands. UUID values resolve saved CLIs from `GET /v2/clis`; every other value is run as an installation command. In saved mode, an explicit empty array disables saved CLIs for this launch. CLI clients expose repeatable `--cli`."
},
"mcps": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/V2SavedMcpReference"
},
{
"$ref": "#/components/schemas/V2InlineMcpDefinition"
}
]
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Mcps",
"description": "Saved MCP references or inline portable definitions. In saved mode, an explicit empty array disables saved MCPs for this launch."
},
"setup_commands": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Setup Commands",
"description": "Shell commands run sequentially in the prepared repository before the agent starts. In saved mode, an explicit empty array disables saved setup commands for this launch. CLI clients expose repeatable `--setup-command`."
},
"cleanup_commands": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Cleanup Commands",
"description": "Best-effort shell commands run sequentially after agent execution and result capture, before sandbox deletion. In saved mode, an explicit empty array disables saved cleanup commands for this launch. CLI clients expose repeatable `--cleanup-command`."
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs",
"description": "Independent attempts for every prompt-agent pair. Defaults to the saved eval value or 1 for a direct run."
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Tags",
"description": "Direct create-and-run form only. Optional labels saved on the created eval. CLI clients may expose this string array as a repeatable `--tag` flag."
},
"repository": {
"type": "string",
"minLength": 1,
"title": "Repository",
"description": "Direct create-and-run form only. A saved repository ID, built-in alias such as `nextjs-starter`, or a public GitHub HTTPS URL."
},
"env": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"maxProperties": 100,
"title": "Env",
"description": "Write-only environment variables for this launch. Values are stored only in the queued job's private configuration.",
"writeOnly": true
},
"skills": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Skills",
"description": "Additional public skill packages to install before the agent starts in either request form, using GitHub `owner/repository` references such as `resend/resend-skills`. CLI clients may expose this string array as a repeatable `--skill` flag."
},
"skill_ids": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Skill Ids",
"description": "Direct create-and-run form only. Reusable skill IDs from `GET /v2/skills` to install before the agent starts."
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Web-retrieval policy for this launch. Overrides the selected configuration or saved eval when provided; direct runs default to `default`."
}
},
"additionalProperties": false,
"type": "object",
"title": "CreateV2EvalRunRequest",
"description": "Start an eval run using one of two flat request forms. Saved runs require `eval_id` and use saved simulation defaults unless the request replaces them. Direct create-and-run requests require `prompts`, `judges`, and `agent`. No separate mode field is required.",
"examples": [
{
"env": {
"LIGHTSAGE_API_KEY": "secret-value"
},
"eval_id": "eval_123"
},
{
"agent": [
"codex:gpt-5-4",
"claude-code:claude-opus-4-8"
],
"judges": [
"The requested workflow succeeds.",
"The generated project passes its tests."
],
"name": "SDK simulation",
"persona": "Platform engineer",
"prompts": [
"Complete the task with the CLI.",
"Complete the task with the MCP server."
],
"repository": "nextjs-starter",
"runs": 2,
"skills": [
"resend/resend-skills"
],
"tags": [
"sdk",
"smoke-test"
]
}
]
},
"CreateV2PromptRequest": {
"properties": {
"topic_id": {
"type": "string",
"title": "Topic Id",
"description": "Prompt topic ID from `GET /v2/prompts/topics`."
},
"text": {
"type": "string",
"minLength": 1,
"title": "Text"
},
"platform_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Platform Ids",
"description": "Answer-platform IDs from the prompt configuration. Omit to attach none."
},
"run_settings": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunSettingsInput"
},
{
"type": "null"
}
],
"description": "Run settings that apply to coding-agent runs of this prompt. Omitted fields keep their current or default values."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"topic_id",
"text"
],
"title": "CreateV2PromptRequest"
},
"CreateV2PromptRunRequest": {
"properties": {
"prompt_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 100,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Prompt Ids",
"description": "Prompt IDs from `GET /v2/prompts`. Omit this field to run all active prompts."
},
"force": {
"type": "boolean",
"title": "Force",
"description": "Run even when a prompt already ran today on the configured platform and model.",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"title": "CreateV2PromptRunRequest",
"examples": [
{
"prompt_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
},
{
"force": true
}
]
},
"CreateV2PromptsRequest": {
"properties": {
"prompts": {
"items": {
"$ref": "#/components/schemas/CreateV2PromptRequest"
},
"type": "array",
"maxItems": 100,
"minItems": 1,
"title": "Prompts"
}
},
"type": "object",
"required": [
"prompts"
],
"title": "CreateV2PromptsRequest"
},
"CreateV2RepositoryRequest": {
"properties": {
"name": {
"type": "string",
"minLength": 1,
"title": "Name"
},
"repo_url": {
"type": "string",
"minLength": 1,
"title": "Repo Url"
},
"ref": {
"type": "string",
"title": "Ref",
"description": "Branch, tag, or commit SHA.",
"default": "main"
},
"subdir": {
"type": "string",
"title": "Subdir",
"description": "Project root inside the repository.",
"default": ""
},
"install_steps": {
"items": {
"type": "string"
},
"type": "array",
"title": "Install Steps"
},
"framework": {
"type": "string",
"enum": [
"fastify",
"nuxt",
"express",
"spa-js",
"angular",
"react",
"fastapi",
"vite",
"nextjs",
"custom"
],
"title": "Framework",
"default": "custom"
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"repo_url"
],
"title": "CreateV2RepositoryRequest"
},
"EvalTemplate": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name",
"description": "Organization-visible name for this reusable template."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Description",
"description": "Optional guidance describing when to use the template."
},
"prompt": {
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Prompt filled into the new eval form when the template is applied, or the scenario for Agent Preference, where `{{competitor_name}}` names the brand each comparison is against. Requests that create evals from a template still supply their own prompts."
},
"eval_type": {
"type": "string",
"enum": [
"custom_eval",
"agent_preference"
],
"title": "Eval Type",
"description": "Kind of eval the template creates. A template only applies to evals of the same type.",
"default": "custom_eval"
},
"included_components": {
"items": {
"type": "string",
"enum": [
"judges",
"targets",
"persona",
"competitors",
"tag",
"category",
"runs",
"schedule",
"repository",
"environment",
"search_grounding",
"skills",
"mcp_servers",
"clis",
"brand_docs",
"github_pr",
"runtime_commands"
]
},
"type": "array",
"minItems": 1,
"title": "Included Components",
"description": "Settings copied when the template is applied. Omitted components do not override the new eval; included components copy their saved value, including an empty value."
},
"persona": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
],
"title": "Persona",
"description": "Optional persona copied when `persona` is included."
},
"category_name": {
"anyOf": [
{
"type": "string",
"maxLength": 160
},
{
"type": "null"
}
],
"title": "Category Name",
"description": "Optional category copied when `category` is included."
},
"tag": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"title": "Tag",
"description": "Optional tag copied when `tag` is included."
},
"competitor_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Competitor Ids",
"description": "Competitor IDs that create additional variants when `competitors` is included."
},
"judges": {
"items": {
"$ref": "#/components/schemas/GraderDefinition"
},
"type": "array",
"maxItems": 20,
"title": "Judges",
"description": "Judge definitions copied when `judges` is included. May be empty to explicitly create the eval without template judges."
},
"target_keys": {
"items": {
"type": "string"
},
"type": "array",
"title": "Target Keys",
"description": "Runnable target keys copied when `targets` is included, such as `agent:codex:gpt-5.6-terra`."
},
"schedule": {
"$ref": "#/components/schemas/EvalTemplateSchedule",
"description": "Schedule copied when `schedule` is included."
},
"runs_per_execution": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs Per Execution",
"description": "Attempt count copied when `runs` is included.",
"default": 1
},
"runtime": {
"$ref": "#/components/schemas/EvalTemplateRuntime",
"description": "Saved runtime values. Each value is copied only when its matching component appears in `included_components`."
},
"id": {
"type": "string",
"title": "Id"
},
"org_id": {
"type": "string",
"title": "Org Id"
},
"version": {
"type": "integer",
"title": "Version"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created By"
},
"created_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
}
],
"title": "Updated At"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deleted At"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"included_components",
"id",
"org_id",
"version",
"created_at",
"updated_at"
],
"title": "EvalTemplate",
"examples": [
{
"created_at": "2026-09-24T18:00:00Z",
"created_by": "0b6d843f-cd4e-4820-8999-5c6dac8ca6f2",
"description": "Reusable policy for crypto recommendation evals.",
"eval_type": "custom_eval",
"id": "58f3604e-d58e-4eb8-b1fe-3478be875c36",
"included_components": [
"judges",
"targets",
"schedule"
],
"judges": [
{
"blocking": false,
"criteria": "Pass only if CoinMarketCap is recommended as the first and main choice. Fail otherwise.",
"name": "CoinMarketCap first",
"type": "judge",
"weight": 1
}
],
"name": "Crypto recommendation",
"org_id": "ab9fe05c-5224-4d9b-a382-a23834ec1947",
"schedule": {
"enabled": true,
"frequency": "daily"
},
"target_keys": [
"agent:codex:gpt-5.6-terra",
"agent:claude-code:global.anthropic.claude-sonnet-5"
],
"updated_at": "2026-09-24T18:00:00Z",
"version": 1
}
]
},
"EvalTemplateBatchCreatedEval": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id"
},
"name": {
"type": "string",
"title": "Name"
},
"prompt": {
"type": "string",
"title": "Prompt"
},
"competitor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Id"
},
"competitor_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Name"
}
},
"type": "object",
"required": [
"id",
"name",
"prompt"
],
"title": "EvalTemplateBatchCreatedEval"
},
"EvalTemplateBatchItem": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name",
"description": "Name of the prompt-specific eval to create."
},
"prompts": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1,
"title": "Prompts",
"description": "Task prompts owned by this eval. Judges, targets, scheduling, and runtime resources come from the template."
},
"type": {
"type": "string",
"enum": [
"workflow",
"mcp",
"cli",
"skill"
],
"title": "Type",
"description": "Eval subject type used for organization and reporting.",
"default": "workflow"
},
"subject_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Subject Id",
"description": "Optional subject identifier associated with this eval."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"prompts"
],
"title": "EvalTemplateBatchItem",
"description": "Prompt-specific fields combined with the referenced template."
},
"EvalTemplateBatchResponse": {
"properties": {
"template_id": {
"type": "string",
"title": "Template Id"
},
"template_version": {
"type": "integer",
"title": "Template Version"
},
"created_count": {
"type": "integer",
"title": "Created Count"
},
"base_count": {
"type": "integer",
"title": "Base Count"
},
"variant_count": {
"type": "integer",
"title": "Variant Count"
},
"results": {
"items": {
"$ref": "#/components/schemas/EvalTemplateBatchResult"
},
"type": "array",
"title": "Results"
}
},
"type": "object",
"required": [
"template_id",
"template_version",
"created_count",
"base_count",
"variant_count"
],
"title": "EvalTemplateBatchResponse",
"examples": [
{
"base_count": 1,
"created_count": 2,
"results": [
{
"base": {
"eval_id": "b7e8fd2f-197f-4114-8206-6083d3079752",
"id": "d3336acd-5637-40d0-a1da-89b142590c4c",
"name": "BTC price fetcher",
"prompt": "Fetch the current BTC price."
},
"input_index": 0,
"name": "BTC price fetcher",
"variants": [
{
"competitor_id": "3f70aa73-bfbe-4494-934d-72a60989115d",
"competitor_name": "Competitor",
"eval_id": "c08e3af8-9bed-4544-81d1-d5c9f3c227cb",
"id": "8ebcbe4d-c35b-4bce-a1a7-5aff1d02a0fb",
"name": "BTC price fetcher",
"prompt": "Fetch the current BTC price."
}
]
}
],
"template_id": "58f3604e-d58e-4eb8-b1fe-3478be875c36",
"template_version": 1,
"variant_count": 1
}
]
},
"EvalTemplateBatchResult": {
"properties": {
"input_index": {
"type": "integer",
"title": "Input Index"
},
"name": {
"type": "string",
"title": "Name"
},
"base": {
"$ref": "#/components/schemas/EvalTemplateBatchCreatedEval"
},
"variants": {
"items": {
"$ref": "#/components/schemas/EvalTemplateBatchCreatedEval"
},
"type": "array",
"title": "Variants"
}
},
"type": "object",
"required": [
"input_index",
"name",
"base"
],
"title": "EvalTemplateBatchResult"
},
"EvalTemplateRuntime": {
"properties": {
"starting_project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Starting Project Id",
"description": "Optional reusable repository workspace ID."
},
"environment_profile_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Environment Profile Ids",
"description": "Environment profile IDs copied into each created eval."
},
"include_env_vars": {
"type": "boolean",
"title": "Include Env Vars",
"description": "Whether selected environment profiles are enabled.",
"default": true
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Web-retrieval policy copied into each created eval.",
"default": "default"
},
"skill_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Skill Ids",
"description": "Reusable skill IDs copied into each created eval."
},
"mcp_server_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mcp Server Ids",
"description": "Reusable MCP server IDs copied into each created eval."
},
"cli_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Cli Ids",
"description": "Reusable CLI IDs copied into each created eval."
},
"include_brand_docs": {
"type": "boolean",
"title": "Include Brand Docs",
"description": "Whether organization documentation is included at runtime.",
"default": false
},
"run_on_github_pr": {
"type": "boolean",
"title": "Run On Github Pr",
"description": "Whether each created eval is configured for GitHub pull requests.",
"default": false
},
"setup_commands": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Setup Commands",
"description": "Shell commands run before each eval attempt, in order."
},
"cleanup_commands": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"title": "Cleanup Commands",
"description": "Shell commands run after each eval attempt, in order."
}
},
"additionalProperties": false,
"type": "object",
"title": "EvalTemplateRuntime",
"description": "Reusable runtime resources copied into each created eval."
},
"EvalTemplateSchedule": {
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"description": "Whether each eval created from the template receives a schedule.",
"default": false
},
"frequency": {
"type": "string",
"enum": [
"daily",
"every_other_day",
"weekly"
],
"title": "Frequency",
"description": "Schedule cadence used when `enabled` is true.",
"default": "weekly"
}
},
"additionalProperties": false,
"type": "object",
"title": "EvalTemplateSchedule",
"description": "Schedule copied into every eval created from the template."
},
"EvalTemplatesResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/EvalTemplate"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "EvalTemplatesResponse"
},
"GraderDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"type": {
"type": "string",
"title": "Type"
},
"needle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Needle"
},
"needles": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Needles"
},
"pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pattern"
},
"case_sensitive": {
"type": "boolean",
"title": "Case Sensitive",
"default": false
},
"criteria": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Criteria"
},
"metric": {
"anyOf": [
{
"type": "string",
"enum": [
"tool_calls",
"time",
"cost"
]
},
{
"type": "null"
}
],
"title": "Metric"
},
"min_score": {
"anyOf": [
{
"type": "number",
"maximum": 1.0,
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Min Score"
},
"max_value": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0.0
},
{
"type": "null"
}
],
"title": "Max Value"
},
"weight": {
"type": "number",
"title": "Weight",
"default": 1.0
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"description": "Whether a failed or missing result from this grader fails the entire eval regardless of the aggregate score.",
"default": false
}
},
"type": "object",
"required": [
"name",
"type"
],
"title": "GraderDefinition"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ListOpportunitiesResponse": {
"properties": {
"start_date": {
"type": "string",
"title": "Start Date",
"description": "Window start actually used, after resolving `start_date`, `since`, or the default."
},
"end_date": {
"type": "string",
"title": "End Date"
},
"data": {
"items": {
"$ref": "#/components/schemas/PublicPromptOpportunity"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count",
"description": "Capped by `limit`; not the total available."
},
"summary": {
"additionalProperties": true,
"type": "object",
"title": "Summary",
"description": "Breakdowns of the returned items only; each sums to `count`."
}
},
"type": "object",
"required": [
"start_date",
"end_date",
"count"
],
"title": "ListOpportunitiesResponse"
},
"PromptBatchError": {
"properties": {
"index": {
"type": "integer",
"title": "Index",
"description": "Zero-based index into the submitted `prompts` array."
},
"text": {
"type": "string",
"title": "Text"
},
"error": {
"type": "string",
"title": "Error"
}
},
"type": "object",
"required": [
"index",
"text",
"error"
],
"title": "PromptBatchError"
},
"PublicAgentAnalyticsCountryListResponse": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"start_date": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date",
"title": "End Date"
},
"countries": {
"items": {
"$ref": "#/components/schemas/PublicAgentCountry"
},
"type": "array",
"title": "Countries",
"description": "Visits from coding agents and AI assistants per country, most visits first. The country is located from the IP address the request came from. For hosted assistants such as ChatGPT that is usually the provider's servers, not the person who asked; for coding agents it is usually the developer's machine."
}
},
"type": "object",
"required": [
"site_id",
"start_date",
"end_date"
],
"title": "PublicAgentAnalyticsCountryListResponse"
},
"PublicAgentAnalyticsErrorPageListResponse": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"start_date": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date",
"title": "End Date"
},
"status_codes_tracked": {
"type": "boolean",
"title": "Status Codes Tracked",
"description": "Whether any request to the site in the date range reported a status code. Status codes come from server-side tracking such as a log drain or middleware; when this is false, an empty `pages` list does not mean there were no errors."
},
"pages": {
"items": {
"$ref": "#/components/schemas/PublicAgentErrorPage"
},
"type": "array",
"title": "Pages",
"description": "Most error requests first."
}
},
"type": "object",
"required": [
"site_id",
"start_date",
"end_date",
"status_codes_tracked"
],
"title": "PublicAgentAnalyticsErrorPageListResponse"
},
"PublicAgentAnalyticsPageListResponse": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"start_date": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date",
"title": "End Date"
},
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent",
"description": "The coding agent the pages were filtered to, when `agent` was set. Its visits are in `coding` and `ai_total`; the other counts are 0."
},
"pages": {
"items": {
"$ref": "#/components/schemas/PublicAgentTrafficPage"
},
"type": "array",
"title": "Pages"
}
},
"type": "object",
"required": [
"site_id",
"start_date",
"end_date"
],
"title": "PublicAgentAnalyticsPageListResponse"
},
"PublicAgentAnalyticsSite": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"domain": {
"type": "string",
"title": "Domain"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source",
"description": "Kind of site: `website`, `docs`, `app`, or `blog`."
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At",
"description": "When the first tracked visit created the site."
}
},
"type": "object",
"required": [
"site_id",
"domain"
],
"title": "PublicAgentAnalyticsSite"
},
"PublicAgentAnalyticsSiteListResponse": {
"properties": {
"sites": {
"items": {
"$ref": "#/components/schemas/PublicAgentAnalyticsSite"
},
"type": "array",
"title": "Sites"
}
},
"type": "object",
"title": "PublicAgentAnalyticsSiteListResponse"
},
"PublicAgentAnalyticsSourceListResponse": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"start_date": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date",
"title": "End Date"
},
"sources": {
"items": {
"$ref": "#/components/schemas/PublicAgentTrafficSource"
},
"type": "array",
"title": "Sources",
"description": "Most visits first."
}
},
"type": "object",
"required": [
"site_id",
"start_date",
"end_date"
],
"title": "PublicAgentAnalyticsSourceListResponse"
},
"PublicAgentAnalyticsSummary": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"start_date": {
"type": "string",
"format": "date",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date",
"title": "End Date"
},
"current": {
"$ref": "#/components/schemas/PublicAgentTrafficTotals",
"description": "Visits from `start_date` through `end_date`."
},
"previous": {
"$ref": "#/components/schemas/PublicAgentTrafficTotals",
"description": "Visits over the same number of days just before `start_date`, for comparison."
}
},
"type": "object",
"required": [
"site_id",
"start_date",
"end_date",
"current",
"previous"
],
"title": "PublicAgentAnalyticsSummary"
},
"PublicAgentCountry": {
"properties": {
"country": {
"type": "string",
"title": "Country",
"description": "Two-letter ISO country code of the request, or `unknown`."
},
"visits": {
"type": "integer",
"title": "Visits"
}
},
"type": "object",
"required": [
"country",
"visits"
],
"title": "PublicAgentCountry"
},
"PublicAgentErrorPage": {
"properties": {
"path": {
"type": "string",
"title": "Path"
},
"status_code": {
"type": "integer",
"title": "Status Code",
"description": "HTTP status returned, such as 404."
},
"visits": {
"type": "integer",
"title": "Visits",
"description": "Requests to this path that got this status."
},
"ai_visits": {
"type": "integer",
"title": "Ai Visits",
"description": "Of `visits`, those from coding agents and AI bots."
},
"last_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Seen",
"description": "Time of the latest error."
},
"sources": {
"items": {
"$ref": "#/components/schemas/PublicAgentErrorSource"
},
"type": "array",
"title": "Sources",
"description": "Who got the error, most requests first."
}
},
"type": "object",
"required": [
"path",
"status_code",
"visits",
"ai_visits"
],
"title": "PublicAgentErrorPage"
},
"PublicAgentErrorSource": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Agent or bot name, as in the traffic sources list, or `people`."
},
"kind": {
"type": "string",
"enum": [
"agent",
"bot",
"other",
"people"
],
"title": "Kind"
},
"type": {
"type": "string",
"enum": [
"coding",
"user",
"search",
"training",
"other",
"people"
],
"title": "Type"
},
"visits": {
"type": "integer",
"title": "Visits",
"description": "Requests from this source that got the error."
}
},
"type": "object",
"required": [
"name",
"kind",
"type",
"visits"
],
"title": "PublicAgentErrorSource"
},
"PublicAgentTrafficPage": {
"properties": {
"path": {
"type": "string",
"title": "Path"
},
"coding": {
"type": "integer",
"title": "Coding",
"description": "Visits from coding agents such as Claude Code, Codex, and Cursor."
},
"user": {
"type": "integer",
"title": "User",
"description": "Visits from AI assistants fetching a page because a user asked, such as ChatGPT-User."
},
"search": {
"type": "integer",
"title": "Search",
"description": "Visits from AI search indexers such as OAI-SearchBot."
},
"training": {
"type": "integer",
"title": "Training",
"description": "Visits from AI training crawlers such as GPTBot."
},
"other": {
"type": "integer",
"title": "Other",
"description": "Visits from bots with no AI purpose, such as search engine crawlers."
},
"people": {
"type": "integer",
"title": "People",
"description": "Visits from people."
},
"ai_total": {
"type": "integer",
"title": "Ai Total",
"description": "Sum of `coding`, `user`, `search`, and `training` visits."
},
"last_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Seen",
"description": "Day of the latest visit, in `YYYY-MM-DD` format."
}
},
"type": "object",
"required": [
"path",
"coding",
"user",
"search",
"training",
"other",
"people",
"ai_total"
],
"title": "PublicAgentTrafficPage"
},
"PublicAgentTrafficSource": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Agent or bot name, such as `claude-code` or `GPTBot`."
},
"kind": {
"type": "string",
"enum": [
"agent",
"bot",
"other",
"people"
],
"title": "Kind",
"description": "`agent` for coding agents, `bot` for AI bots, `other` for bots with no AI purpose, and `people` for all human visits as one row."
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Provider",
"description": "Company that runs the bot."
},
"type": {
"type": "string",
"enum": [
"coding",
"user",
"search",
"training",
"other",
"people"
],
"title": "Type"
},
"visits": {
"type": "integer",
"title": "Visits"
}
},
"type": "object",
"required": [
"name",
"kind",
"type",
"visits"
],
"title": "PublicAgentTrafficSource"
},
"PublicAgentTrafficTotals": {
"properties": {
"coding": {
"type": "integer",
"title": "Coding",
"description": "Visits from coding agents such as Claude Code, Codex, and Cursor."
},
"user": {
"type": "integer",
"title": "User",
"description": "Visits from AI assistants fetching a page because a user asked, such as ChatGPT-User."
},
"search": {
"type": "integer",
"title": "Search",
"description": "Visits from AI search indexers such as OAI-SearchBot."
},
"training": {
"type": "integer",
"title": "Training",
"description": "Visits from AI training crawlers such as GPTBot."
},
"other": {
"type": "integer",
"title": "Other",
"description": "Visits from bots with no AI purpose, such as search engine crawlers."
},
"people": {
"type": "integer",
"title": "People",
"description": "Visits from people."
},
"ai_total": {
"type": "integer",
"title": "Ai Total",
"description": "Sum of `coding`, `user`, `search`, and `training` visits."
},
"total": {
"type": "integer",
"title": "Total",
"description": "Every visit, AI or not."
}
},
"type": "object",
"required": [
"coding",
"user",
"search",
"training",
"other",
"people",
"ai_total",
"total"
],
"title": "PublicAgentTrafficTotals"
},
"PublicCitedUrl": {
"properties": {
"url": {
"type": "string",
"title": "Url",
"description": "Most frequently observed variant of the cited URL."
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain",
"description": "Domain of the cited URL."
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title",
"description": "Page title, when available."
},
"favicon_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Favicon Url",
"description": "Page favicon URL, when available."
},
"is_company_link": {
"type": "boolean",
"title": "Is Company Link",
"description": "Whether the URL belongs to an owned company domain."
},
"citation_count": {
"type": "integer",
"title": "Citation Count",
"description": "Number of citations to this normalized URL in the date range."
},
"prompt_count": {
"type": "integer",
"title": "Prompt Count",
"description": "Number of distinct active prompts that cited this URL."
},
"platform_names": {
"items": {
"type": "string"
},
"type": "array",
"title": "Platform Names",
"description": "Platforms that cited this URL in the selected date range."
}
},
"type": "object",
"required": [
"url",
"is_company_link",
"citation_count",
"prompt_count"
],
"title": "PublicCitedUrl"
},
"PublicCitedUrlDateRange": {
"properties": {
"start_date": {
"type": "string",
"title": "Start Date",
"description": "Start date used for the calculation."
},
"end_date": {
"type": "string",
"title": "End Date",
"description": "End date used for the calculation."
},
"active_prompts_only": {
"type": "boolean",
"title": "Active Prompts Only",
"description": "Whether only currently active prompts were included.",
"default": true
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "PublicCitedUrlDateRange"
},
"PublicCompany": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Logo Url"
},
"relationship": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Relationship",
"description": "The company relationship: `primary` for the organization's own company or `competitor` for a tracked competitor."
}
},
"type": "object",
"required": [
"name"
],
"title": "PublicCompany"
},
"PublicCompetitorRow": {
"properties": {
"company": {
"$ref": "#/components/schemas/PublicCompany"
},
"recommendation_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recommendation Score",
"description": "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings \u203a Navigation. Rows do not sum to 1."
},
"recommendation_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recommendation Score Rank"
},
"visibility_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Visibility Score",
"description": "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded. A run can mention several companies, so rows do not sum to 1."
},
"visibility_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Visibility Score Rank"
},
"share_of_voice": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Share Of Voice",
"description": "The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`."
},
"share_of_voice_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Share Of Voice Rank",
"description": "Rank by `share_of_voice` among tracked companies, highest first."
},
"average_position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Position",
"description": "Mean mention position in AI responses; 1 is first and lower is better. 0 when never mentioned."
},
"average_position_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Average Position Rank",
"description": "Companies with an `average_position` of 0 rank last."
}
},
"type": "object",
"required": [
"company"
],
"title": "PublicCompetitorRow"
},
"PublicCriterionVerdict": {
"properties": {
"criterion": {
"type": "string",
"title": "Criterion",
"description": "One mandatory requirement from the judge criteria."
},
"verdict": {
"type": "string",
"enum": [
"PASS",
"FAIL",
"NOT_VERIFIED"
],
"title": "Verdict",
"description": "`PASS` when the evidence shows the requirement was met, `FAIL` when it shows it was not, and `NOT_VERIFIED` when the evidence cannot confirm it. Any `FAIL` or `NOT_VERIFIED` fails the run, whatever the score."
},
"evidence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Evidence",
"description": "Short evidence the judge gave for the verdict."
}
},
"type": "object",
"required": [
"criterion",
"verdict"
],
"title": "PublicCriterionVerdict"
},
"PublicCurrentVisibilityResponse": {
"properties": {
"company": {
"$ref": "#/components/schemas/PublicCompany"
},
"recommendation_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recommendation Score",
"description": "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings \u203a Navigation."
},
"recommendation_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recommendation Score Rank"
},
"visibility_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Visibility Score",
"description": "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded."
},
"visibility_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Visibility Score Rank"
},
"share_of_voice": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Share Of Voice",
"description": "The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`."
},
"share_of_voice_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Share Of Voice Rank",
"description": "Rank by `share_of_voice` among tracked companies, highest first."
},
"average_position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Position",
"description": "Mean mention position in AI responses; 1 is first and lower is better."
},
"average_position_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Average Position Rank"
},
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Date",
"description": "Latest prompt-run date in the range."
},
"start_date": {
"type": "string",
"title": "Start Date"
},
"end_date": {
"type": "string",
"title": "End Date"
},
"active_prompts_only": {
"type": "boolean",
"title": "Active Prompts Only",
"default": true
},
"has_data": {
"type": "boolean",
"title": "Has Data"
}
},
"type": "object",
"required": [
"company",
"start_date",
"end_date",
"has_data"
],
"title": "PublicCurrentVisibilityResponse"
},
"PublicEvalRunEnvironment": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Environment ID, as listed by the environments operation."
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Environment name when the run was queued."
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At",
"description": "Environment version the run used: when its name or variables last changed before the run was queued. Null if the environment had not changed since versioning was introduced."
},
"queued_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Queued At",
"description": "When the run was queued with this environment."
},
"variable_names": {
"items": {
"type": "string"
},
"type": "array",
"title": "Variable Names",
"description": "Variable names supplied to the run. Values are never returned."
},
"inline": {
"type": "boolean",
"title": "Inline",
"description": "True when variables were supplied inline with the run request instead of from a saved environment.",
"default": false
},
"changed_since_queued": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Changed Since Queued",
"description": "True when the saved environment has been edited or deleted since the run was queued, so a rerun would use different values. Null when unknown or for inline environments."
}
},
"type": "object",
"title": "PublicEvalRunEnvironment",
"description": "Non-secret summary of the environment an eval run was queued with."
},
"PublicEvalRunProgress": {
"properties": {
"total": {
"type": "integer",
"title": "Total",
"default": 0
},
"queued": {
"type": "integer",
"title": "Queued",
"default": 0
},
"running": {
"type": "integer",
"title": "Running",
"default": 0
},
"completed": {
"type": "integer",
"title": "Completed",
"default": 0
},
"failed": {
"type": "integer",
"title": "Failed",
"default": 0
},
"cancelled": {
"type": "integer",
"title": "Cancelled",
"default": 0
},
"retrying": {
"type": "integer",
"title": "Retrying",
"description": "Recoverable child jobs waiting to be retried. These remain active and are excluded from `percent`.",
"default": 0
},
"interrupted": {
"type": "integer",
"title": "Interrupted",
"description": "Deprecated compatibility alias for `retrying`; use `retrying`.",
"default": 0,
"deprecated": true
},
"percent": {
"type": "number",
"title": "Percent",
"description": "The percentage of child jobs in a final state (`completed`, `failed`, or `cancelled`). It can reach `100` while the parent job is still summarizing, so use `status` to detect completion.",
"default": 0
}
},
"type": "object",
"title": "PublicEvalRunProgress"
},
"PublicGraderResult": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Grader name as configured on the eval."
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label",
"description": "Display name for the check, when the grader sets one."
},
"passed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Passed",
"description": "Whether this check passed."
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Score",
"description": "Score from 0 to 1 for checks that score partially, such as judges; null for pass/fail checks."
},
"deductions": {
"items": {
"type": "string"
},
"type": "array",
"title": "Deductions",
"description": "Specific shortcomings the check recorded, even when it passed. A judge can pass with a score below 1 and still list deductions here; those checks do not appear in `failure_reasons`."
},
"details": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Reasoning or check output explaining the verdict."
},
"criteria_verdicts": {
"items": {
"$ref": "#/components/schemas/PublicCriterionVerdict"
},
"type": "array",
"title": "Criteria Verdicts",
"description": "Judges only: a verdict for each mandatory requirement in the judge criteria. Empty for other checks and for runs graded before per-requirement verdicts were recorded."
}
},
"type": "object",
"required": [
"name"
],
"title": "PublicGraderResult"
},
"PublicOkResponse": {
"properties": {
"ok": {
"type": "boolean",
"title": "Ok"
}
},
"type": "object",
"required": [
"ok"
],
"title": "PublicOkResponse"
},
"PublicPlatformRef": {
"properties": {
"platform_id": {
"type": "string",
"title": "Platform Id"
},
"name": {
"type": "string",
"title": "Name"
},
"icon_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Icon Url"
},
"mention_count": {
"type": "integer",
"title": "Mention Count",
"description": "Prompt runs where the company was mentioned on this platform in the date range.",
"default": 0
},
"prompt_run_count": {
"type": "integer",
"title": "Prompt Run Count",
"description": "Total prompt runs on this platform in the date range.",
"default": 0
}
},
"type": "object",
"required": [
"platform_id",
"name"
],
"title": "PublicPlatformRef"
},
"PublicPromptOpportunity": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Stable across requests and windows for the same finding. There is no retrieve endpoint."
},
"type": {
"type": "string",
"title": "Type",
"description": "Determines which undeclared extra fields the object carries, such as `winner_brand_name` on `almost_winning`."
},
"category": {
"type": "string",
"title": "Category"
},
"priority": {
"type": "string",
"title": "Priority"
},
"title": {
"type": "string",
"title": "Title"
},
"description": {
"type": "string",
"title": "Description"
},
"action": {
"type": "string",
"title": "Action"
},
"execution_prompt": {
"type": "string",
"title": "Execution Prompt"
},
"impact_score": {
"type": "number",
"title": "Impact Score",
"description": "Out of 100. Recomputed per window, so the same `id` can score differently across windows."
},
"created_at": {
"type": "string",
"title": "Created At",
"description": "Time of the request, since opportunities are computed per call."
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"type",
"category",
"priority",
"title",
"description",
"action",
"execution_prompt",
"impact_score",
"created_at"
],
"title": "PublicPromptOpportunity"
},
"PublicPromptPlatform": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "PublicPromptPlatform"
},
"PublicPromptTag": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "PublicPromptTag"
},
"PublicPromptTopic": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "PublicPromptTopic"
},
"PublicPromptVisibilityDateRange": {
"properties": {
"start_date": {
"type": "string",
"title": "Start Date"
},
"end_date": {
"type": "string",
"title": "End Date"
},
"latest_run_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Latest Run Date"
},
"active_prompts_only": {
"type": "boolean",
"title": "Active Prompts Only",
"default": true
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "PublicPromptVisibilityDateRange"
},
"PublicPromptVisibilityMetrics": {
"properties": {
"recommendation_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recommendation Score",
"description": "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings \u203a Navigation."
},
"recommendation_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recommendation Score Rank"
},
"visibility_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Visibility Score",
"description": "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded."
},
"share_of_voice": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Share Of Voice",
"description": "The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`."
},
"average_position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Position",
"description": "Mean mention position in AI responses; 1 is first and lower is better. 0 when runs produced no mentions."
},
"citation_count": {
"type": "integer",
"title": "Citation Count",
"description": "Owned-domain citations only.",
"default": 0
},
"run_count": {
"type": "integer",
"title": "Run Count",
"description": "One per prompt, platform, and run date.",
"default": 0
}
},
"type": "object",
"title": "PublicPromptVisibilityMetrics"
},
"PublicPromptVisibilityReportResponse": {
"properties": {
"company": {
"$ref": "#/components/schemas/PublicCompany"
},
"date_range": {
"$ref": "#/components/schemas/PublicPromptVisibilityDateRange"
},
"has_data": {
"type": "boolean",
"title": "Has Data"
},
"summary": {
"$ref": "#/components/schemas/PublicPromptVisibilitySummary"
},
"topics": {
"items": {
"$ref": "#/components/schemas/PublicTopicVisibilityRow"
},
"type": "array",
"title": "Topics"
}
},
"type": "object",
"required": [
"company",
"date_range",
"has_data",
"summary"
],
"title": "PublicPromptVisibilityReportResponse"
},
"PublicPromptVisibilityRow": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"metrics": {
"$ref": "#/components/schemas/PublicPromptVisibilityMetrics"
}
},
"type": "object",
"required": [
"id",
"text",
"metrics"
],
"title": "PublicPromptVisibilityRow"
},
"PublicPromptVisibilitySummary": {
"properties": {
"prompt_count": {
"type": "integer",
"title": "Prompt Count"
},
"topic_count": {
"type": "integer",
"title": "Topic Count"
},
"metrics": {
"$ref": "#/components/schemas/PublicPromptVisibilityMetrics"
}
},
"type": "object",
"required": [
"prompt_count",
"topic_count",
"metrics"
],
"title": "PublicPromptVisibilitySummary"
},
"PublicSeriesPoint": {
"properties": {
"date": {
"type": "string",
"title": "Date",
"description": "Only dates with prompt runs appear, so a series can be shorter than the range."
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Value"
}
},
"type": "object",
"required": [
"date"
],
"title": "PublicSeriesPoint"
},
"PublicSiteAuditIssue": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Check identifier such as `canonical-url`; the same id recurs on every page failing that check."
},
"category": {
"type": "string",
"title": "Category",
"description": "One of `access`, `delivery`, `discoverability`, `metadata`, or `quality`."
},
"severity": {
"type": "string",
"enum": [
"warning",
"error"
],
"title": "Severity"
},
"message": {
"type": "string",
"title": "Message"
},
"recommendation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Recommendation"
},
"evidence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Evidence"
}
},
"type": "object",
"required": [
"id",
"category",
"severity",
"message"
],
"title": "PublicSiteAuditIssue"
},
"PublicSiteAuditListResponse": {
"properties": {
"audit": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicSiteAuditSnapshot"
},
{
"type": "null"
}
]
},
"pages": {
"items": {
"$ref": "#/components/schemas/PublicSiteAuditPage"
},
"type": "array",
"title": "Pages"
}
},
"type": "object",
"title": "PublicSiteAuditListResponse"
},
"PublicSiteAuditPage": {
"properties": {
"site_id": {
"type": "string",
"title": "Site Id"
},
"url": {
"type": "string",
"title": "Url"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Score",
"description": "The page audit score, from 0 to 100."
},
"grade": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grade"
},
"status": {
"type": "string",
"title": "Status",
"description": "Health band from the findings, not a processing state."
},
"priority": {
"type": "string",
"title": "Priority"
},
"issue_count": {
"type": "integer",
"title": "Issue Count"
},
"issues": {
"items": {
"$ref": "#/components/schemas/PublicSiteAuditIssue"
},
"type": "array",
"title": "Issues"
}
},
"type": "object",
"required": [
"site_id",
"url",
"status",
"priority",
"issue_count"
],
"title": "PublicSiteAuditPage"
},
"PublicSiteAuditSnapshot": {
"properties": {
"url": {
"type": "string",
"title": "Url"
},
"status": {
"type": "string",
"title": "Status",
"description": "Processing status of the audit run, unlike the per-page health `status`."
},
"score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Score",
"description": "The overall audit score, from 0 to 100; it is not the mean of the per-page scores."
},
"grade": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grade"
},
"generated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Generated At"
},
"total_pages": {
"type": "integer",
"title": "Total Pages"
},
"pages_with_issues": {
"type": "integer",
"title": "Pages With Issues"
},
"failed_pages": {
"type": "integer",
"title": "Failed Pages",
"description": "Pages whose processing failed, not pages with issues."
}
},
"type": "object",
"required": [
"url",
"status",
"total_pages",
"pages_with_issues",
"failed_pages"
],
"title": "PublicSiteAuditSnapshot"
},
"PublicTopCitedUrlsResponse": {
"properties": {
"date_range": {
"$ref": "#/components/schemas/PublicCitedUrlDateRange"
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Platform",
"description": "Platform selector applied to the results, or null for all platforms."
},
"source_type": {
"type": "string",
"enum": [
"all",
"owned",
"external"
],
"title": "Source Type",
"description": "Whether the results include all, owned, or external URLs."
},
"has_data": {
"type": "boolean",
"title": "Has Data",
"description": "Whether any citations matched the selected filters."
},
"count": {
"type": "integer",
"title": "Count",
"description": "Number of URL rows returned."
},
"data": {
"items": {
"$ref": "#/components/schemas/PublicCitedUrl"
},
"type": "array",
"title": "Data",
"description": "Cited URLs ranked by citation count in descending order."
}
},
"type": "object",
"required": [
"date_range",
"source_type",
"has_data",
"count"
],
"title": "PublicTopCitedUrlsResponse"
},
"PublicTopicVisibilityRow": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"prompt_count": {
"type": "integer",
"title": "Prompt Count"
},
"metrics": {
"$ref": "#/components/schemas/PublicPromptVisibilityMetrics"
},
"prompts": {
"items": {
"$ref": "#/components/schemas/PublicPromptVisibilityRow"
},
"type": "array",
"title": "Prompts"
}
},
"type": "object",
"required": [
"id",
"name",
"prompt_count",
"metrics"
],
"title": "PublicTopicVisibilityRow"
},
"PublicVisibilityByPlatform": {
"properties": {
"platforms": {
"items": {
"$ref": "#/components/schemas/PublicPlatformRef"
},
"type": "array",
"title": "Platforms"
},
"recommendation_score": {
"additionalProperties": {
"items": {
"$ref": "#/components/schemas/PublicSeriesPoint"
},
"type": "array"
},
"type": "object",
"title": "Recommendation Score",
"description": "Recommendation score series keyed by `platform_id`. Empty unless the organization turns on Recommendation Score under Settings \u203a Navigation."
},
"visibility_score": {
"additionalProperties": {
"items": {
"$ref": "#/components/schemas/PublicSeriesPoint"
},
"type": "array"
},
"type": "object",
"title": "Visibility Score",
"description": "Visibility score series keyed by `platform_id`: the share of that platform's prompt runs each day that mention the company (0 to 1)."
},
"citations": {
"additionalProperties": {
"items": {
"$ref": "#/components/schemas/PublicSeriesPoint"
},
"type": "array"
},
"type": "object",
"title": "Citations",
"description": "Owned-domain citation counts keyed by platform_id."
}
},
"type": "object",
"title": "PublicVisibilityByPlatform"
},
"PublicVisibilityDateRange": {
"properties": {
"start_date": {
"type": "string",
"title": "Start Date"
},
"end_date": {
"type": "string",
"title": "End Date"
},
"granularity": {
"type": "string",
"title": "Granularity",
"default": "day"
},
"latest_run_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Latest Run Date"
},
"active_prompts_only": {
"type": "boolean",
"title": "Active Prompts Only",
"default": true
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "PublicVisibilityDateRange"
},
"PublicVisibilityOverviewResponse": {
"properties": {
"company": {
"$ref": "#/components/schemas/PublicCompany"
},
"date_range": {
"$ref": "#/components/schemas/PublicVisibilityDateRange"
},
"has_data": {
"type": "boolean",
"title": "Has Data"
},
"snapshot": {
"$ref": "#/components/schemas/PublicVisibilitySnapshot"
},
"timeseries": {
"$ref": "#/components/schemas/PublicVisibilityTimeseries"
},
"by_platform": {
"$ref": "#/components/schemas/PublicVisibilityByPlatform"
},
"competitors": {
"items": {
"$ref": "#/components/schemas/PublicCompetitorRow"
},
"type": "array",
"title": "Competitors",
"description": "Includes the primary company."
}
},
"type": "object",
"required": [
"company",
"date_range",
"has_data",
"snapshot",
"timeseries",
"by_platform"
],
"title": "PublicVisibilityOverviewResponse"
},
"PublicVisibilitySnapshot": {
"properties": {
"recommendation_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recommendation Score",
"description": "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings \u203a Navigation."
},
"recommendation_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recommendation Score Rank"
},
"visibility_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Visibility Score",
"description": "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded."
},
"visibility_score_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Visibility Score Rank"
},
"share_of_voice": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Share Of Voice",
"description": "The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`."
},
"share_of_voice_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Share Of Voice Rank",
"description": "Rank by `share_of_voice` among tracked companies, highest first."
},
"average_position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Position",
"description": "Mean mention position in AI responses; 1 is first and lower is better."
},
"average_position_rank": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Average Position Rank"
},
"total_citations": {
"type": "integer",
"title": "Total Citations",
"description": "Owned-domain citations across all platforms; 0, not `null`, with no prompt runs.",
"default": 0
}
},
"type": "object",
"title": "PublicVisibilitySnapshot"
},
"PublicVisibilityTimeseries": {
"properties": {
"recommendation_score": {
"items": {
"$ref": "#/components/schemas/PublicSeriesPoint"
},
"type": "array",
"title": "Recommendation Score",
"description": "Company recommendation score per day. Empty unless the organization turns on Recommendation Score under Settings \u203a Navigation."
},
"visibility_score": {
"items": {
"$ref": "#/components/schemas/PublicSeriesPoint"
},
"type": "array",
"title": "Visibility Score",
"description": "Company visibility score per day: the share of prompt runs that mention the company (0 to 1)."
}
},
"type": "object",
"title": "PublicVisibilityTimeseries"
},
"SearchGroundingMode": {
"type": "string",
"enum": [
"disabled",
"enabled",
"default"
],
"title": "SearchGroundingMode",
"description": "Requested web-retrieval behavior for an eval run."
},
"UpdateEvalTemplateRequest": {
"properties": {
"expected_template_version": {
"type": "integer",
"minimum": 1.0,
"title": "Expected Template Version"
},
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"description": {
"type": "string",
"maxLength": 1000,
"title": "Description"
},
"prompt": {
"type": "string",
"maxLength": 20000,
"title": "Prompt"
},
"eval_type": {
"type": "string",
"enum": [
"custom_eval",
"agent_preference"
],
"title": "Eval Type"
},
"included_components": {
"anyOf": [
{
"items": {
"type": "string",
"enum": [
"judges",
"targets",
"persona",
"competitors",
"tag",
"category",
"runs",
"schedule",
"repository",
"environment",
"search_grounding",
"skills",
"mcp_servers",
"clis",
"brand_docs",
"github_pr",
"runtime_commands"
]
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Included Components"
},
"persona": {
"type": "string",
"maxLength": 500,
"title": "Persona"
},
"category_name": {
"type": "string",
"maxLength": 160,
"title": "Category Name"
},
"tag": {
"type": "string",
"maxLength": 100,
"title": "Tag"
},
"competitor_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Competitor Ids"
},
"judges": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/GraderDefinition"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Judges"
},
"target_keys": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Target Keys"
},
"schedule": {
"anyOf": [
{
"$ref": "#/components/schemas/EvalTemplateSchedule"
},
{
"type": "null"
}
]
},
"runs_per_execution": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs Per Execution"
},
"runtime": {
"anyOf": [
{
"$ref": "#/components/schemas/EvalTemplateRuntime"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateEvalTemplateRequest",
"examples": [
{
"expected_template_version": 1,
"name": "Crypto recommendation \u2014 daily",
"schedule": {
"enabled": true,
"frequency": "daily"
}
}
]
},
"UpdatePromptTopicRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "UpdatePromptTopicRequest"
},
"UpdateTaskRequest": {
"properties": {
"status": {
"type": "string",
"enum": [
"new",
"in_progress",
"added_to_sheet",
"done",
"dismissed",
"snoozed"
],
"title": "Status",
"description": "The new task status. `added_to_sheet` and `snoozed` tasks are listed only when `status=all`."
},
"priority": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low"
],
"title": "Priority"
},
"assignee_user_id": {
"type": "string",
"title": "Assignee User Id"
},
"action_type": {
"type": "string",
"enum": [
"agent_discovery",
"agent_usability"
],
"title": "Action Type"
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateTaskRequest"
},
"UpdateV2AgentPreferenceEvalRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"prompts": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Prompts",
"description": "Buying or build questions the agent answers by choosing between your company and the competitor. CLI clients expose this as repeatable `--prompt`."
},
"agent": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10
},
{
"type": "null"
}
],
"title": "Agent",
"description": "Runnable agents from `GET /v2/agents`. An empty array saves the comparison without default agents. CLI clients expose repeatable `--agent`."
},
"persona": {
"type": "string",
"maxLength": 160,
"title": "Persona",
"description": "Set to null to clear the saved persona."
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
]
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Tags"
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateV2AgentPreferenceEvalRequest"
},
"UpdateV2EvalConfigurationRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"repository_id": {
"type": "string",
"title": "Repository Id"
},
"environment_id": {
"type": "string",
"title": "Environment Id"
},
"mcp_server_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Mcp Server Ids"
},
"cli_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Cli Ids"
},
"skill_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Skill Ids"
},
"skills": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Skills",
"description": "Public skill packages saved with this configuration, using GitHub `owner/repository` references."
},
"include_docs": {
"type": "boolean",
"title": "Include Docs"
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Replacement web-retrieval policy. Omit it to keep the saved value."
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateV2EvalConfigurationRequest"
},
"UpdateV2EvalRequest": {
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"title": "Name"
},
"prompts": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Prompts"
},
"judges": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1
},
{
"type": "null"
}
],
"title": "Judges",
"description": "Replacement success criteria for the eval."
},
"agent": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10
},
{
"type": "null"
}
],
"title": "Agent"
},
"persona": {
"type": "string",
"maxLength": 160,
"title": "Persona",
"description": "Replacement eval persona. Pass null to clear it; omit it to leave the saved value unchanged."
},
"clis": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Clis",
"description": "Replacement saved CLI IDs or shell installation commands. UUID values resolve saved CLIs; every other value is an installation command. Pass an empty array to clear all CLIs."
},
"mcps": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/V2SavedMcpReference"
},
{
"$ref": "#/components/schemas/V2InlineMcpDefinition"
}
]
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Mcps"
},
"setup_commands": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Setup Commands",
"description": "Replacement setup commands. Pass an empty array to clear all saved setup commands."
},
"cleanup_commands": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Cleanup Commands",
"description": "Replacement cleanup commands. Pass an empty array to clear all saved cleanup commands."
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Replacement web-retrieval policy. Omit it to keep the saved value."
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Replacement labels for the eval. Pass an empty array to clear all tags."
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateV2EvalRequest"
},
"UpdateV2PromptRequest": {
"properties": {
"text": {
"type": "string",
"minLength": 1,
"title": "Text"
},
"topic_id": {
"type": "string",
"title": "Topic Id",
"description": "Prompt topic ID from `GET /v2/prompts/topics`."
},
"platform_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Platform Ids",
"description": "Replacement list of answer-platform IDs."
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
],
"title": "Status"
},
"is_branded": {
"type": "boolean",
"title": "Is Branded",
"description": "Marks the prompt as branded or unbranded. Omit to keep the current value; changing `text` does not change it."
},
"run_settings": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunSettingsInput"
},
{
"type": "null"
}
],
"description": "Run settings that apply to coding-agent runs of this prompt. Omitted fields keep their current or default values."
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateV2PromptRequest"
},
"UpdateV2RepositoryRequest": {
"properties": {
"name": {
"type": "string",
"minLength": 1,
"title": "Name"
},
"repo_url": {
"type": "string",
"minLength": 1,
"title": "Repo Url"
},
"ref": {
"type": "string",
"title": "Ref"
},
"subdir": {
"type": "string",
"title": "Subdir"
},
"install_steps": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Install Steps"
},
"framework": {
"type": "string",
"enum": [
"fastify",
"nuxt",
"express",
"spa-js",
"angular",
"react",
"fastapi",
"vite",
"nextjs",
"custom"
],
"title": "Framework"
},
"enabled": {
"type": "boolean",
"title": "Enabled"
}
},
"additionalProperties": false,
"type": "object",
"title": "UpdateV2RepositoryRequest"
},
"V2Agent": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Runnable agent ID combining the harness and model, such as `claude-code:claude-opus-4-8`."
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable harness and model name."
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2Agent"
},
"V2AgentPreferenceCompany": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
}
},
"type": "object",
"title": "V2AgentPreferenceCompany"
},
"V2AgentPreferenceCompetitor": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Competitor ID to pass as `competitor_id`."
},
"name": {
"type": "string",
"title": "Name"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Logo Url"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2AgentPreferenceCompetitor"
},
"V2AgentPreferenceCompetitorsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2AgentPreferenceCompetitor"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2AgentPreferenceCompetitorsResponse"
},
"V2AgentPreferenceEval": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Eval ID. Pass it as `eval_id` to `POST /v2/eval-runs` to run the comparison."
},
"name": {
"type": "string",
"title": "Name"
},
"competitor": {
"anyOf": [
{
"$ref": "#/components/schemas/V2AgentPreferenceCompetitor"
},
{
"type": "null"
}
],
"description": "The competitor your company is compared against. Null when the competitor is no longer tracked."
},
"prompts": {
"items": {
"type": "string"
},
"type": "array",
"title": "Prompts"
},
"judges": {
"items": {
"type": "string"
},
"type": "array",
"title": "Judges",
"description": "Criteria applied to each response. The first one decides which company the agent recommended and cannot be changed."
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"title": "Agent"
},
"persona": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Persona"
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"default": "default"
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs",
"default": 1
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2AgentPreferenceEval"
},
"V2AgentPreferenceEvalsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2AgentPreferenceEval"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2AgentPreferenceEvalsResponse"
},
"V2AgentPreferenceHeadToHeadResponse": {
"properties": {
"company": {
"$ref": "#/components/schemas/V2AgentPreferenceCompany",
"description": "Your company, the side every record is counted from."
},
"summary": {
"$ref": "#/components/schemas/V2AgentPreferenceRecord",
"description": "Combined record across every competitor."
},
"data": {
"items": {
"$ref": "#/components/schemas/V2AgentPreferenceMatchup"
},
"type": "array",
"title": "Data",
"description": "One record per competitor, most comparisons first."
},
"count": {
"type": "integer",
"title": "Count",
"description": "The number of items in `data`."
},
"attempts_considered": {
"type": "integer",
"title": "Attempts Considered",
"description": "Recent attempts read to build the records. Attempts without a usable recommendation are read but not counted as comparisons."
},
"limit": {
"type": "integer",
"title": "Limit"
},
"truncated": {
"type": "boolean",
"title": "Truncated",
"description": "True when older attempts exist beyond `limit` and were not counted."
}
},
"type": "object",
"required": [
"company",
"summary",
"count",
"attempts_considered",
"limit",
"truncated"
],
"title": "V2AgentPreferenceHeadToHeadResponse"
},
"V2AgentPreferenceMatchup": {
"properties": {
"wins": {
"type": "integer",
"title": "Wins",
"description": "Attempts where the agent recommended your company."
},
"losses": {
"type": "integer",
"title": "Losses",
"description": "Attempts where the agent recommended the competitor."
},
"ties": {
"type": "integer",
"title": "Ties",
"description": "Attempts where the agent recommended both equally or neither."
},
"comparisons": {
"type": "integer",
"title": "Comparisons",
"description": "`wins + losses + ties`."
},
"win_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Win Rate",
"description": "`wins / comparisons` from 0 to 1. Null when there are no comparisons."
},
"competitor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Id",
"description": "Null when the competitor is no longer tracked."
},
"competitor_name": {
"type": "string",
"title": "Competitor Name"
},
"competitor_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Domain"
},
"eval_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Eval Ids",
"description": "Agent Preference evals that contributed to this record."
}
},
"type": "object",
"required": [
"wins",
"losses",
"ties",
"comparisons",
"competitor_name"
],
"title": "V2AgentPreferenceMatchup"
},
"V2AgentPreferenceRecord": {
"properties": {
"wins": {
"type": "integer",
"title": "Wins",
"description": "Attempts where the agent recommended your company."
},
"losses": {
"type": "integer",
"title": "Losses",
"description": "Attempts where the agent recommended the competitor."
},
"ties": {
"type": "integer",
"title": "Ties",
"description": "Attempts where the agent recommended both equally or neither."
},
"comparisons": {
"type": "integer",
"title": "Comparisons",
"description": "`wins + losses + ties`."
},
"win_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Win Rate",
"description": "`wins / comparisons` from 0 to 1. Null when there are no comparisons."
}
},
"type": "object",
"required": [
"wins",
"losses",
"ties",
"comparisons"
],
"title": "V2AgentPreferenceRecord"
},
"V2AgentPreferenceResult": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Result ID for one attempt."
},
"eval_id": {
"type": "string",
"title": "Eval Id"
},
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent",
"description": "Runnable agent combining the harness and model."
},
"preference_result": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PreferenceResult"
},
{
"type": "null"
}
],
"description": "Null when the attempt did not produce a usable recommendation, such as an attempt that ended in an error."
},
"latency_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Latency Ms"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"eval_id"
],
"title": "V2AgentPreferenceResult"
},
"V2AgentPreferenceResultsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2AgentPreferenceResult"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count",
"description": "The number of items in `data`."
},
"total": {
"type": "integer",
"title": "Total",
"description": "All recorded attempts for this eval."
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"count",
"total",
"limit",
"offset"
],
"title": "V2AgentPreferenceResultsResponse"
},
"V2AgentsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2Agent"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2AgentsResponse"
},
"V2Cli": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"binary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Binary"
},
"docs_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Docs Url"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2Cli"
},
"V2ClisResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2Cli"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2ClisResponse"
},
"V2EnvironmentsResponse": {
"properties": {
"data": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Data",
"description": "Environment profiles with IDs, names, and variable names only."
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2EnvironmentsResponse"
},
"V2Eval": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"prompts": {
"items": {
"type": "string"
},
"type": "array",
"title": "Prompts"
},
"judges": {
"items": {
"type": "string"
},
"type": "array",
"title": "Judges"
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"title": "Agent"
},
"persona": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Persona"
},
"clis": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/V2SavedCliReference"
},
{
"$ref": "#/components/schemas/V2InlineCliReference"
}
]
},
"type": "array",
"title": "Clis"
},
"mcps": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/V2SavedMcpReference"
},
{
"$ref": "#/components/schemas/V2InlineMcpDefinition"
}
]
},
"type": "array",
"title": "Mcps"
},
"setup_commands": {
"items": {
"type": "string"
},
"type": "array",
"title": "Setup Commands"
},
"cleanup_commands": {
"items": {
"type": "string"
},
"type": "array",
"title": "Cleanup Commands"
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Saved web-retrieval policy: disabled, enabled, or default.",
"default": "default"
},
"runs": {
"type": "integer",
"maximum": 20.0,
"minimum": 1.0,
"title": "Runs",
"default": 1
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2Eval"
},
"V2EvalConfiguration": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"eval_id": {
"type": "string",
"title": "Eval Id"
},
"name": {
"type": "string",
"title": "Name"
},
"repository_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Repository Id"
},
"environment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Environment Id"
},
"mcp_server_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mcp Server Ids"
},
"cli_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Cli Ids"
},
"skill_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Skill Ids"
},
"skills": {
"items": {
"type": "string"
},
"type": "array",
"title": "Skills",
"description": "Public GitHub `owner/repository` skill packages installed for this configuration."
},
"include_docs": {
"type": "boolean",
"title": "Include Docs",
"default": false
},
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Saved web-retrieval policy: disabled, enabled, or default.",
"default": "default"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"eval_id",
"name"
],
"title": "V2EvalConfiguration"
},
"V2EvalConfigurationsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2EvalConfiguration"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2EvalConfigurationsResponse"
},
"V2EvalResultSummary": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Result ID, not an eval job ID."
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id"
},
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent",
"description": "Runnable agent combining the harness and model."
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt"
},
"prompt_index": {
"type": "integer",
"minimum": 0.0,
"title": "Prompt Index",
"default": 0
},
"repeat_index": {
"type": "integer",
"minimum": 0.0,
"title": "Repeat Index",
"default": 0
},
"passed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Passed"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Score",
"description": "Score from 0 to 1."
},
"failure_reasons": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Failure Reasons",
"description": "Checks that failed, listed even when the result passed overall. Deductions from checks that passed are in `grader_results[].deductions`, not here."
},
"grader_results": {
"items": {
"$ref": "#/components/schemas/PublicGraderResult"
},
"type": "array",
"title": "Grader Results",
"description": "Per-check verdicts behind `score`, including deductions recorded by passing checks."
},
"preference_result": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PreferenceResult"
},
{
"type": "null"
}
],
"description": "Which company the agent recommended. Present only for Agent Preference evals that produced a usable recommendation."
},
"latency_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Latency Ms"
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
]
},
"web_retrieval_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Web Retrieval Observed"
},
"search_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Search Observed"
},
"grounding_qualified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Grounding Qualified",
"description": "Whether the attempt satisfied the requested grounding experiment. Null means the default mode was used or isolation could not be proven."
},
"grounding_qualification_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grounding Qualification Reason"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"environment": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicEvalRunEnvironment"
},
{
"type": "null"
}
],
"description": "The environment this attempt used, without secret values. Null when the attempt had no environment."
}
},
"type": "object",
"required": [
"id"
],
"title": "V2EvalResultSummary"
},
"V2EvalRun": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Run ID to use when polling eval-run status."
},
"job_id": {
"type": "string",
"title": "Job Id",
"description": "Alias of `id` for the durable parent job."
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id",
"description": "Saved eval definition ID, including one created by a direct run."
},
"eval_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Name",
"description": "Display name captured for the eval when the run was created."
},
"configuration_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Configuration Id"
},
"persona": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Persona",
"description": "Perspective applied to every attempt in this simulation."
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"title": "Agent",
"description": "Runnable agents selected for this simulation."
},
"prompt_count": {
"type": "integer",
"minimum": 1.0,
"title": "Prompt Count",
"description": "Number of prompts included in the simulation.",
"default": 1
},
"runs": {
"type": "integer",
"minimum": 1.0,
"title": "Runs",
"description": "Independent attempts requested for every prompt-agent pair.",
"default": 1
},
"attempt_count": {
"type": "integer",
"minimum": 1.0,
"title": "Attempt Count",
"description": "Total concrete attempts after all fan-out dimensions.",
"default": 1
},
"status": {
"type": "string",
"title": "Status",
"description": "Terminal values: `completed`, `failed`, and `cancelled`. Recoverable interruptions are reported as `running` with stage `retrying`."
},
"stage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stage"
},
"dispatch_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Dispatch Id"
},
"progress": {
"$ref": "#/components/schemas/PublicEvalRunProgress"
},
"estimated_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Cost"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
}
},
"type": "object",
"required": [
"id",
"job_id",
"status"
],
"title": "V2EvalRun"
},
"V2EvalRunAnalysis": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Persisted eval analysis ID."
},
"result_id": {
"type": "string",
"title": "Result Id",
"description": "Concrete eval result ID analyzed for this attempt."
},
"attempt_id": {
"type": "string",
"title": "Attempt Id",
"description": "Child eval-attempt ID used to correlate the analysis with trace events."
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id",
"description": "Public eval definition ID, not the backing executable eval ID."
},
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent",
"description": "Runnable agent used for this concrete attempt."
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt",
"description": "Exact task prompt used for this concrete attempt."
},
"prompt_index": {
"type": "integer",
"minimum": 0.0,
"title": "Prompt Index",
"description": "Zero-based prompt index within the submitted simulation.",
"default": 0
},
"variant_key": {
"type": "string",
"title": "Variant Key",
"description": "Runtime variant that produced this result.",
"default": "default"
},
"repeat_index": {
"type": "integer",
"minimum": 0.0,
"title": "Repeat Index",
"description": "Zero-based repeat index within the submitted run.",
"default": 0
},
"analysis_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Analysis Version",
"description": "Version of the analysis pipeline that produced this payload."
},
"analysis": {
"additionalProperties": true,
"type": "object",
"title": "Analysis",
"description": "Persisted eval_run_analysis payload, including verdict, outcome, findings, bottleneck, and analysis sections."
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"result_id",
"attempt_id"
],
"title": "V2EvalRunAnalysis"
},
"V2EvalRunDetail": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Run ID to use when polling eval-run status."
},
"job_id": {
"type": "string",
"title": "Job Id",
"description": "Alias of `id` for the durable parent job."
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id",
"description": "Saved eval definition ID, including one created by a direct run."
},
"eval_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Name",
"description": "Display name captured for the eval when the run was created."
},
"configuration_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Configuration Id"
},
"persona": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Persona",
"description": "Perspective applied to every attempt in this simulation."
},
"agent": {
"items": {
"type": "string"
},
"type": "array",
"title": "Agent",
"description": "Runnable agents selected for this simulation."
},
"prompt_count": {
"type": "integer",
"minimum": 1.0,
"title": "Prompt Count",
"description": "Number of prompts included in the simulation.",
"default": 1
},
"runs": {
"type": "integer",
"minimum": 1.0,
"title": "Runs",
"description": "Independent attempts requested for every prompt-agent pair.",
"default": 1
},
"attempt_count": {
"type": "integer",
"minimum": 1.0,
"title": "Attempt Count",
"description": "Total concrete attempts after all fan-out dimensions.",
"default": 1
},
"status": {
"type": "string",
"title": "Status",
"description": "Terminal values: `completed`, `failed`, and `cancelled`. Recoverable interruptions are reported as `running` with stage `retrying`."
},
"stage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stage"
},
"dispatch_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Dispatch Id"
},
"progress": {
"$ref": "#/components/schemas/PublicEvalRunProgress"
},
"estimated_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Cost"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"results": {
"items": {
"$ref": "#/components/schemas/V2EvalResultSummary"
},
"type": "array",
"title": "Results",
"description": "Per-attempt outcomes for this run. Empty while the run is active; populated as attempts finish."
},
"analysis": {
"items": {
"$ref": "#/components/schemas/V2EvalRunAnalysis"
},
"type": "array",
"title": "Analysis",
"description": "Per-attempt analysis for this run. Empty until an attempt has been analyzed."
},
"results_truncated": {
"type": "boolean",
"title": "Results Truncated",
"description": "True when the run produced more results than the inline cap. The remaining results are not included in this response.",
"default": false
}
},
"type": "object",
"required": [
"id",
"job_id",
"status"
],
"title": "V2EvalRunDetail"
},
"V2EvalRunTraceEvent": {
"properties": {
"run_id": {
"type": "string",
"title": "Run Id"
},
"eval_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Id"
},
"eval_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Eval Name"
},
"configuration_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Configuration Id"
},
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent"
},
"prompt_index": {
"type": "integer",
"minimum": 0.0,
"title": "Prompt Index",
"default": 0
},
"repeat_index": {
"type": "integer",
"minimum": 0.0,
"title": "Repeat Index",
"default": 0
},
"child_job_id": {
"type": "string",
"title": "Child Job Id",
"description": "Child eval-attempt ID associated with the event."
},
"event_id": {
"type": "integer",
"title": "Event Id"
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Timestamp"
},
"category": {
"type": "string",
"title": "Category"
},
"type": {
"type": "string",
"title": "Type",
"description": "Event type. Events are not tool invocations: one invocation usually emits a `tool_call` event and a `tool_result` event, and can emit extra `tool_call` updates as its arguments stream. Count invocations with the result's `tool_calls`, not with trace events."
},
"message": {
"type": "string",
"title": "Message"
},
"data": {
"additionalProperties": true,
"type": "object",
"title": "Data",
"description": "Sanitized event payload."
}
},
"type": "object",
"required": [
"run_id",
"child_job_id",
"event_id",
"category",
"type",
"message"
],
"title": "V2EvalRunTraceEvent"
},
"V2EvalRunTraceResponse": {
"properties": {
"run_id": {
"type": "string",
"title": "Run Id"
},
"status": {
"type": "string",
"title": "Status"
},
"progress": {
"$ref": "#/components/schemas/PublicEvalRunProgress"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"data": {
"items": {
"$ref": "#/components/schemas/V2EvalRunTraceEvent"
},
"type": "array",
"title": "Data"
},
"next_after_id": {
"type": "integer",
"minimum": 0.0,
"title": "Next After Id",
"description": "Cursor to pass as `after_id` when requesting the next page."
},
"has_more": {
"type": "boolean",
"title": "Has More"
}
},
"type": "object",
"required": [
"run_id",
"status",
"next_after_id",
"has_more"
],
"title": "V2EvalRunTraceResponse"
},
"V2EvalRunsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2EvalRun"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"count",
"limit",
"offset"
],
"title": "V2EvalRunsResponse"
},
"V2EvalsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2Eval"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2EvalsResponse"
},
"V2InlineCliReference": {
"properties": {
"install_command": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"title": "Install Command",
"description": "Shell command to install this CLI before the agent starts."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"install_command"
],
"title": "V2InlineCliReference"
},
"V2InlineMcpDefinition": {
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"title": "Name",
"description": "Stable server name used in the selected agent's MCP config."
},
"type": {
"type": "string",
"enum": [
"http",
"sse",
"stdio"
],
"title": "Type"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url",
"description": "HTTPS endpoint for an `http` or `sse` MCP server."
},
"headers": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"maxProperties": 50,
"title": "Headers",
"description": "HTTP headers. Reference run secrets with `${VARIABLE_NAME}` instead of embedding credentials."
},
"command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Command",
"description": "Executable command for a `stdio` MCP server."
},
"args": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 100,
"title": "Args"
},
"env": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"maxProperties": 100,
"title": "Env",
"description": "Environment mapping for a `stdio` MCP server. Values may reference the run environment's variables with `${VARIABLE_NAME}`; secrets (names ending in KEY, TOKEN, SECRET or PASSWORD) must."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"type"
],
"title": "V2InlineMcpDefinition"
},
"V2ListPromptsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2PromptResponse"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"data",
"count"
],
"title": "V2ListPromptsResponse"
},
"V2ListTasksResponse": {
"properties": {
"action_date": {
"type": "string",
"title": "Action Date",
"description": "The requested action date. It defaults to today in UTC even when `data` spans every date."
},
"status": {
"type": "string",
"enum": [
"active",
"todo",
"new",
"in_progress",
"completed",
"done",
"dismissed",
"all"
],
"title": "Status",
"description": "The requested queue slice; this value is not itself a task status."
},
"batch_number": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Batch Number"
},
"latest_batch_number": {
"type": "integer",
"title": "Latest Batch Number",
"default": 0
},
"data": {
"items": {
"$ref": "#/components/schemas/V2PublicTask"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
},
"active_count": {
"type": "integer",
"title": "Active Count",
"default": 0
},
"in_progress_count": {
"type": "integer",
"title": "In Progress Count",
"default": 0
},
"completed_count": {
"type": "integer",
"title": "Completed Count",
"default": 0
},
"done_count": {
"type": "integer",
"title": "Done Count",
"default": 0
},
"dismissed_count": {
"type": "integer",
"title": "Dismissed Count",
"default": 0
},
"history_count": {
"type": "integer",
"title": "History Count",
"default": 0
},
"has_history": {
"type": "boolean",
"title": "Has History",
"default": false
},
"can_fetch_next_batch": {
"type": "boolean",
"title": "Can Fetch Next Batch",
"default": false
},
"generated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Generated At"
}
},
"type": "object",
"required": [
"action_date",
"status",
"count"
],
"title": "V2ListTasksResponse"
},
"V2McpServer": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"server_name": {
"type": "string",
"title": "Server Name"
},
"transport": {
"type": "string",
"title": "Transport"
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
}
},
"type": "object",
"required": [
"id",
"name",
"server_name",
"transport"
],
"title": "V2McpServer"
},
"V2McpServersResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2McpServer"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2McpServersResponse"
},
"V2PreferenceResult": {
"properties": {
"outcome": {
"type": "string",
"enum": [
"won",
"lost",
"tie"
],
"title": "Outcome",
"description": "`won` when the agent recommended your company, `lost` when it recommended the competitor, and `tie` when it recommended both equally or neither."
},
"winner_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Winner Name",
"description": "The recommended company. Null on a tie."
},
"competitor_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Name"
},
"competitor_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor Domain"
}
},
"type": "object",
"required": [
"outcome"
],
"title": "V2PreferenceResult",
"description": "Which company an agent recommended, from your company's side."
},
"V2PromptBatchResponse": {
"properties": {
"created": {
"items": {
"$ref": "#/components/schemas/V2PromptResponse"
},
"type": "array",
"title": "Created"
},
"count": {
"type": "integer",
"title": "Count"
},
"errors": {
"items": {
"$ref": "#/components/schemas/PromptBatchError"
},
"type": "array",
"title": "Errors"
}
},
"type": "object",
"required": [
"created",
"count"
],
"title": "V2PromptBatchResponse"
},
"V2PromptOpportunity": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Stable across requests and windows for the same finding and retrievable within a selected date window."
},
"type": {
"type": "string",
"title": "Type",
"description": "Determines which undeclared extra fields the object carries, such as `winner_brand_name` on `almost_winning`."
},
"category": {
"type": "string",
"title": "Category"
},
"priority": {
"type": "string",
"title": "Priority"
},
"title": {
"type": "string",
"title": "Title"
},
"description": {
"type": "string",
"title": "Description"
},
"action": {
"type": "string",
"title": "Action"
},
"execution_prompt": {
"type": "string",
"title": "Execution Prompt"
},
"impact_score": {
"type": "number",
"title": "Impact Score",
"description": "Out of 100. Recomputed per window, so the same `id` can score differently across windows."
},
"created_at": {
"type": "string",
"title": "Created At",
"description": "Time of the request, since opportunities are computed per call."
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"type",
"category",
"priority",
"title",
"description",
"action",
"execution_prompt",
"impact_score",
"created_at"
],
"title": "V2PromptOpportunity"
},
"V2PromptResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"topic_id": {
"type": "string",
"title": "Topic Id"
},
"text": {
"type": "string",
"title": "Text"
},
"is_branded": {
"type": "boolean",
"title": "Is Branded",
"description": "Whether the prompt text names your own brand. Detected when the prompt is created, and can be set explicitly.",
"default": false
},
"language_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Language Id"
},
"region_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Region Id"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"archived"
],
"title": "Status",
"description": "The prompt lifecycle status. Only `active` prompts run on schedule."
},
"topic": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicPromptTopic"
},
{
"type": "null"
}
]
},
"platforms": {
"items": {
"$ref": "#/components/schemas/PublicPromptPlatform"
},
"type": "array",
"title": "Platforms"
},
"tags": {
"items": {
"$ref": "#/components/schemas/PublicPromptTag"
},
"type": "array",
"title": "Tags"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"run_settings": {
"$ref": "#/components/schemas/V2PromptRunSettings",
"description": "Run settings that apply to coding-agent runs of this prompt."
}
},
"type": "object",
"required": [
"id",
"topic_id",
"text",
"status"
],
"title": "V2PromptResponse"
},
"V2PromptRunBrand": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Logo Url"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2PromptRunBrand"
},
"V2PromptRunCitation": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"url": {
"type": "string",
"title": "Url"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"is_company_link": {
"type": "boolean",
"title": "Is Company Link",
"default": false
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Position"
}
},
"type": "object",
"required": [
"id",
"url"
],
"title": "V2PromptRunCitation"
},
"V2PromptRunDetail": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"prompt_id": {
"type": "string",
"title": "Prompt Id"
},
"prompt": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunPrompt"
},
{
"type": "null"
}
]
},
"platform": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunPlatform"
},
{
"type": "null"
}
]
},
"target_kind": {
"anyOf": [
{
"type": "string",
"enum": [
"answer_engine",
"coding_agent"
]
},
{
"type": "null"
}
],
"title": "Target Kind"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Harness",
"description": "Coding-agent harness for agent runs; otherwise the answer platform identifier."
},
"model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model Id",
"description": "Public model ID. Internal hosting providers are never returned."
},
"run_date": {
"type": "string",
"title": "Run Date"
},
"response_preview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Response Preview"
},
"is_brand_mentioned": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Brand Mentioned"
},
"citation_count": {
"type": "integer",
"title": "Citation Count",
"default": 0
},
"tool_call_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Tool Call Count",
"description": "Coding-agent tool invocations, counting a call and its result once. Matches the length of `tool_calls` on the detail response; null for answer-engine runs."
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Web access mode requested for this run. Null for runs recorded before web access was tracked."
},
"web_retrieval_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Web Retrieval Observed",
"description": "Whether the coding agent was observed searching or fetching from the web. Null when not measured, including answer-engine runs."
},
"search_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Search Observed"
},
"grounding_qualified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Grounding Qualified",
"description": "Whether the run satisfied the requested web access mode. Null means the default mode was used or isolation could not be proven."
},
"grounding_qualification_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grounding Qualification Reason"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"response": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Response"
},
"mentions": {
"items": {
"$ref": "#/components/schemas/V2PromptRunMention"
},
"type": "array",
"title": "Mentions"
},
"citations": {
"items": {
"$ref": "#/components/schemas/V2PromptRunCitation"
},
"type": "array",
"title": "Citations"
},
"tool_calls": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Tool Calls",
"description": "Sanitized coding-agent tool invocations captured for this run, one entry per invocation with its result merged in."
},
"conversation_turns": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Conversation Turns",
"description": "Sanitized interleaved text and tool-call trace captured for this run. It interleaves the agent's `text` turns with `tool_call` turns, so its length is not a tool-call count; use `tool_calls` or `tool_call_count`."
}
},
"type": "object",
"required": [
"id",
"prompt_id",
"run_date"
],
"title": "V2PromptRunDetail"
},
"V2PromptRunJobResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Run ID to poll with `GET /v2/prompts/runs/{run_id}/status`."
},
"job_id": {
"type": "string",
"title": "Job Id",
"description": "Parent job ID. It currently matches `id`."
},
"type": {
"type": "string",
"const": "prompts",
"title": "Type"
},
"source_type": {
"type": "string",
"const": "prompts",
"title": "Source Type"
},
"status": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"running",
"summarizing",
"completed",
"failed",
"cancelled",
"interrupted"
]
},
{
"type": "string"
}
],
"title": "Status",
"description": "Terminal values: `completed`, `failed`, and `cancelled`. Recoverable interruptions are reported as `running` with stage `retrying`."
},
"stage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stage",
"description": "Current lifecycle stage, including `retrying` while interrupted child jobs wait to be reclaimed."
},
"dispatch_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Dispatch Id"
},
"progress": {
"$ref": "#/components/schemas/PublicEvalRunProgress"
},
"estimated_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Cost",
"description": "The estimated credit cost for prompt jobs or estimated USD cost for API Performance jobs. Null when no estimate is available."
},
"eval_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Eval Count"
},
"model_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Model Count"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At",
"description": "Can be set while `status` is still `summarizing`; use `status` to detect completion."
}
},
"type": "object",
"required": [
"id",
"job_id",
"type",
"source_type",
"status"
],
"title": "V2PromptRunJobResponse"
},
"V2PromptRunMention": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"brand": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunBrand"
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Position"
},
"is_recommended": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Recommended"
},
"is_primary": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Primary"
},
"quote": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Quote"
},
"sentiment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sentiment"
}
},
"type": "object",
"required": [
"id"
],
"title": "V2PromptRunMention"
},
"V2PromptRunPlatform": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2PromptRunPlatform"
},
"V2PromptRunPrompt": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"topic": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunTopic"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"id",
"text"
],
"title": "V2PromptRunPrompt"
},
"V2PromptRunSettings": {
"properties": {
"search_grounding": {
"$ref": "#/components/schemas/SearchGroundingMode",
"description": "Web access for coding-agent runs of this prompt. `disabled` blocks web access in the agent sandbox, `enabled` requires the agent to retrieve from the web, and `default` leaves the choice to the agent. Answer engines are not affected. An eval-run target that sets `search_grounding` overrides this setting.",
"default": "default"
},
"web_search_instruction": {
"type": "string",
"enum": [
"omit",
"append",
"both"
],
"title": "Web Search Instruction",
"description": "Whether coding-agent runs append \"Use web search.\" to the prompt. `both` runs the prompt once without and once with the instruction. Ignored when `search_grounding` is `disabled`. Answer engines always receive the prompt as written.",
"default": "omit"
}
},
"type": "object",
"title": "V2PromptRunSettings"
},
"V2PromptRunSettingsInput": {
"properties": {
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Web access for coding-agent runs of this prompt. `disabled` blocks web access in the agent sandbox, `enabled` requires the agent to retrieve from the web, and `default` leaves the choice to the agent. Answer engines are not affected. An eval-run target that sets `search_grounding` overrides this setting."
},
"web_search_instruction": {
"anyOf": [
{
"type": "string",
"enum": [
"omit",
"append",
"both"
]
},
{
"type": "null"
}
],
"title": "Web Search Instruction",
"description": "Whether coding-agent runs append \"Use web search.\" to the prompt. `both` runs the prompt once without and once with the instruction. Ignored when `search_grounding` is `disabled`. Answer engines always receive the prompt as written."
}
},
"additionalProperties": false,
"type": "object",
"title": "V2PromptRunSettingsInput"
},
"V2PromptRunSummary": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"prompt_id": {
"type": "string",
"title": "Prompt Id"
},
"prompt": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunPrompt"
},
{
"type": "null"
}
]
},
"platform": {
"anyOf": [
{
"$ref": "#/components/schemas/V2PromptRunPlatform"
},
{
"type": "null"
}
]
},
"target_kind": {
"anyOf": [
{
"type": "string",
"enum": [
"answer_engine",
"coding_agent"
]
},
{
"type": "null"
}
],
"title": "Target Kind"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Harness",
"description": "Coding-agent harness for agent runs; otherwise the answer platform identifier."
},
"model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model Id",
"description": "Public model ID. Internal hosting providers are never returned."
},
"run_date": {
"type": "string",
"title": "Run Date"
},
"response_preview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Response Preview"
},
"is_brand_mentioned": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Brand Mentioned"
},
"citation_count": {
"type": "integer",
"title": "Citation Count",
"default": 0
},
"tool_call_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Tool Call Count",
"description": "Coding-agent tool invocations, counting a call and its result once. Matches the length of `tool_calls` on the detail response; null for answer-engine runs."
},
"search_grounding": {
"anyOf": [
{
"$ref": "#/components/schemas/SearchGroundingMode"
},
{
"type": "null"
}
],
"description": "Web access mode requested for this run. Null for runs recorded before web access was tracked."
},
"web_retrieval_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Web Retrieval Observed",
"description": "Whether the coding agent was observed searching or fetching from the web. Null when not measured, including answer-engine runs."
},
"search_observed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Search Observed"
},
"grounding_qualified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Grounding Qualified",
"description": "Whether the run satisfied the requested web access mode. Null means the default mode was used or isolation could not be proven."
},
"grounding_qualification_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grounding Qualification Reason"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"prompt_id",
"run_date"
],
"title": "V2PromptRunSummary"
},
"V2PromptRunTopic": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "V2PromptRunTopic"
},
"V2PromptRunsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2PromptRunSummary"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"count",
"limit",
"offset"
],
"title": "V2PromptRunsResponse"
},
"V2PromptTopicsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/PublicPromptTopic"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2PromptTopicsResponse"
},
"V2PublicTask": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"action_date": {
"type": "string",
"title": "Action Date"
},
"batch_number": {
"type": "integer",
"title": "Batch Number"
},
"rank": {
"type": "integer",
"title": "Rank",
"description": "Sort order within the batch, ascending; values need not start at 1."
},
"source_key": {
"type": "string",
"title": "Source Key",
"description": "A finding key namespaced by source, such as `api_perf:https://example.com/docs/cli`."
},
"task_type": {
"type": "string",
"title": "Task Type",
"description": "A free-form label such as `Redirect` or `Docs`; this field is not an enum."
},
"title": {
"type": "string",
"title": "Title"
},
"why": {
"type": "string",
"title": "Why"
},
"next_action": {
"type": "string",
"title": "Next Action"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"execution_prompt": {
"type": "string",
"title": "Execution Prompt"
},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "The task's Markdown write-up covering what went wrong, how to fix it, the impact, and the evidence. Null until the write-up is generated; see `content_status`."
},
"target_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Target Url",
"description": "The page the fix should be made on, when the task targets one."
},
"content_status": {
"type": "string",
"enum": [
"none",
"writing",
"ready",
"failed"
],
"title": "Content Status",
"description": "Progress of the Markdown write-up in `content`.",
"default": "none"
},
"content_written_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content Written At",
"description": "When the write-up in `content` was last generated."
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning"
},
"evidence": {
"additionalProperties": true,
"type": "object",
"title": "Evidence",
"description": "Supporting evidence with keys such as `expected_lift`, `failure_traces`, `source_prompts`, and `source_urls`."
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Score",
"description": "Planner impact score; manually created tasks may be unscored."
},
"effort": {
"type": "string",
"title": "Effort",
"description": "A free-form effort estimate such as `Low` or `Medium`; this field is not an enum."
},
"priority": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Priority"
},
"status": {
"type": "string",
"title": "Status",
"description": "The workflow status. New tasks start as `new`. A task is `in_review` while its content waits to go live, as an open pull request or a CMS draft; it is listed with `in_progress` tasks. `added_to_sheet` and `snoozed` tasks are listed only when `status=all`."
},
"assignee_user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Assignee User Id"
},
"function_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Function Area"
},
"action_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Action Type"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type",
"description": "A free-form source type such as `api_performance`; manually created tasks may not have a source."
},
"source_refs": {
"additionalProperties": true,
"type": "object",
"title": "Source Refs",
"description": "Source references needed to understand or execute the task."
},
"metadata": {
"additionalProperties": true,
"type": "object",
"title": "Metadata",
"description": "Additional task metadata, including `source_key`, `impact_score`, `disposition`, `target_urls`, `edit_locations` (where on the target page each change goes: `url`, `anchor` heading, `placement` of `in`, `after`, or `before`, and `change`), `evidence_summary`, `source_start_date`, and `source_end_date`."
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"action_date",
"batch_number",
"rank",
"source_key",
"task_type",
"title",
"why",
"next_action",
"execution_prompt",
"effort",
"status"
],
"title": "V2PublicTask"
},
"V2RepositoriesResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2Repository"
},
"type": "array",
"title": "Data"
},
"meta": {
"additionalProperties": true,
"type": "object",
"title": "Meta",
"description": "Contains `count`."
}
},
"type": "object",
"title": "V2RepositoriesResponse"
},
"V2Repository": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Value to pass as `repository` in a direct eval run. Built-in templates use aliases such as `nextjs-starter`; saved repositories use their persisted IDs."
},
"kind": {
"type": "string",
"enum": [
"template",
"saved"
],
"title": "Kind",
"description": "Whether the repository is a read-only built-in template or an organization-owned saved repository."
},
"name": {
"type": "string",
"title": "Name"
},
"repo_url": {
"type": "string",
"title": "Repo Url"
},
"ref": {
"type": "string",
"title": "Ref"
},
"subdir": {
"type": "string",
"title": "Subdir",
"default": ""
},
"install_steps": {
"items": {
"type": "string"
},
"type": "array",
"title": "Install Steps"
},
"framework": {
"type": "string",
"enum": [
"fastify",
"nuxt",
"express",
"spa-js",
"angular",
"react",
"fastapi",
"vite",
"nextjs",
"custom"
],
"title": "Framework",
"default": "custom"
},
"enabled": {
"type": "boolean",
"title": "Enabled"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"kind",
"name",
"repo_url",
"ref",
"enabled"
],
"title": "V2Repository"
},
"V2SavedCliReference": {
"properties": {
"id": {
"type": "string",
"minLength": 1,
"title": "Id",
"description": "Saved CLI ID from `GET /v2/clis`."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"id"
],
"title": "V2SavedCliReference"
},
"V2SavedMcpReference": {
"properties": {
"id": {
"type": "string",
"minLength": 1,
"title": "Id",
"description": "Saved MCP server ID from `GET /v2/mcp-servers`."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"id"
],
"title": "V2SavedMcpReference"
},
"V2Skill": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "Slug"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"type": "object",
"required": [
"id",
"name",
"slug"
],
"title": "V2Skill"
},
"V2SkillsResponse": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/V2Skill"
},
"type": "array",
"title": "Data"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"count"
],
"title": "V2SkillsResponse"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
},
"securitySchemes": {
"LightsageApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-Lightsage-Api-Key"
}
}
},
"tags": [
{
"name": "Status",
"description": "Check API availability and validate the calling API key."
},
{
"name": "Visibility",
"description": "Measure visibility, citations, competitors, and prompt performance across answer platforms."
},
{
"name": "Prompts",
"description": "Manage tracked prompts and topics, and inspect their stored runs."
},
{
"name": "Opportunities",
"description": "Review ranked opportunities computed from prompt visibility results."
},
{
"name": "Tasks",
"description": "Manage the persisted action queue and task lifecycle."
},
{
"name": "Site Audits",
"description": "Review website audit results and page-level findings."
},
{
"name": "Agent Analytics",
"description": "See which coding agents, AI bots, and people visit your tracked sites, which pages they read, which pages return errors, and where the visits come from."
},
{
"name": "Evals",
"description": "Define eval tasks, judges, subjects, and saved configurations."
},
{
"name": "Eval Templates",
"description": "Select reusable judges, targets, schedules, metadata, and runtime settings with `POST /v2/eval-templates`, then copy only those settings into prompt-specific evals with `POST /v2/evals/batch`. Templates never contain prompts and remain independent from evals created from them."
},
{
"name": "Eval Runs",
"description": "Start eval runs and inspect their lifecycle state."
},
{
"name": "Eval Results",
"description": "Review completed eval outcomes and diagnostic details."
},
{
"name": "Agent Preference",
"description": "Compare your company head-to-head with a tracked competitor. Create a comparison with `POST /v2/agent-preference/evals`, run it with `POST /v2/eval-runs`, then read which company agents recommended."
},
{
"name": "Agents",
"description": "List runnable coding-agent harness and model combinations."
},
{
"name": "Repositories",
"description": "Manage reusable Git repository workspaces."
},
{
"name": "Environments",
"description": "List reusable runtime environments without exposing secret values."
},
{
"name": "MCP Servers",
"description": "List reusable MCP server integrations without exposing credentials."
},
{
"name": "CLIs",
"description": "List reusable command-line interfaces without exposing setup commands."
},
{
"name": "Skills",
"description": "List reusable skills available to workflows and evals."
}
]
}