{
"components": {
"schemas": {
"AlertCapacity": {
"description": "How many alerts the project holds against its per-project cap.",
"properties": {
"max": {
"title": "Max",
"type": "integer"
},
"used": {
"title": "Used",
"type": "integer"
}
},
"required": [
"used",
"max"
],
"title": "AlertCapacity",
"type": "object"
},
"AlertDetail": {
"description": "One alert with its full rule: the summary plus filters and gap handling.",
"properties": {
"aggregation": {
"title": "Aggregation",
"type": "string"
},
"alerted_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Alerted At"
},
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"creator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creator"
},
"filters": {
"items": {
"$ref": "#/components/schemas/AlertFilterItem"
},
"title": "Filters",
"type": "array"
},
"id": {
"title": "Id",
"type": "string"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_error_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error At"
},
"last_evaluated_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Evaluated At"
},
"last_notify_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify At"
},
"last_notify_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify Error"
},
"last_notify_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify Status"
},
"measure": {
"title": "Measure",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"no_data_mode": {
"title": "No Data Mode",
"type": "string"
},
"renotify": {
"$ref": "#/components/schemas/AlertRenotify"
},
"severity": {
"title": "Severity",
"type": "string"
},
"severity_changed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Severity Changed At"
},
"status": {
"title": "Status",
"type": "string"
},
"threshold": {
"title": "Threshold",
"type": "number"
},
"threshold_operator": {
"title": "Threshold Operator",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
},
"view": {
"title": "View",
"type": "string"
},
"window": {
"title": "Window",
"type": "string"
}
},
"required": [
"id",
"name",
"view",
"measure",
"aggregation",
"window",
"threshold_operator",
"threshold",
"status",
"severity",
"severity_changed_at",
"alerted_at",
"last_evaluated_at",
"last_error",
"last_error_at",
"last_notify_status",
"last_notify_error",
"last_notify_at",
"create_time",
"update_time",
"creator",
"filters",
"renotify",
"no_data_mode"
],
"title": "AlertDetail",
"type": "object"
},
"AlertFilterItem": {
"description": "A row predicate an alert's measure is evaluated over.\n\nMirrors the alert filter vocabulary in the frontend core package: ``op``\nis one of the two alert operators, and ``key`` names the map entry on a\nkeyed field (metadata).",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Key"
},
"op": {
"enum": [
"=",
"contains"
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
],
"title": "Value"
}
},
"required": [
"field",
"op",
"value"
],
"title": "AlertFilterItem",
"type": "object"
},
"AlertFilterItemRequest": {
"additionalProperties": false,
"description": "A row predicate an alert's measure is evaluated over.",
"properties": {
"field": {
"description": "A span field, e.g. model_name or metadata",
"title": "Field",
"type": "string"
},
"key": {
"description": "The map entry to compare; required for the metadata field",
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains"
],
"title": "Op",
"type": "string"
},
"value": {
"title": "Value",
"type": [
"string",
"number"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "AlertFilterItemRequest",
"type": "object"
},
"AlertListMeta": {
"description": "Pagination plus the project's alert capacity.",
"properties": {
"capacity": {
"$ref": "#/components/schemas/AlertCapacity"
},
"limit": {
"title": "Limit",
"type": "integer"
},
"page": {
"title": "Page",
"type": "integer"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"page",
"limit",
"total",
"capacity"
],
"title": "AlertListMeta",
"type": "object"
},
"AlertRenotify": {
"description": "How often an alert re-notifies while it stays in the alerting state.\n\nKept a single-level object rather than a discriminated union, matching\nthe request-side shape. The cross-field rule is enforced by a validator\ninstead, so a contradictory stored rule fails the detail read closed\nrather than passing through half-typed.",
"properties": {
"interval_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Interval Minutes"
},
"mode": {
"enum": [
"OFF",
"EVERY"
],
"title": "Mode",
"type": "string"
}
},
"required": [
"mode"
],
"title": "AlertRenotify",
"type": "object"
},
"AlertRenotifyRequest": {
"description": "How often an alert re-notifies while it stays in the alerting state.",
"properties": {
"interval_minutes": {
"description": "Minutes between repeat notifications; required when mode is EVERY",
"title": "Interval Minutes",
"type": "integer"
},
"mode": {
"enum": [
"OFF",
"EVERY"
],
"title": "Mode",
"type": "string"
}
},
"required": [
"mode"
],
"title": "AlertRenotifyRequest",
"type": "object"
},
"AlertStatusRequest": {
"additionalProperties": false,
"description": "Body for pausing or resuming an alert.\n\nOnly ACTIVE and PAUSED are settable: PARKED is the evaluator's verdict.",
"properties": {
"project_id": {
"title": "Project Id",
"type": "string"
},
"status": {
"enum": [
"ACTIVE",
"PAUSED"
],
"title": "Status",
"type": "string"
}
},
"required": [
"project_id",
"status"
],
"title": "AlertStatusRequest",
"type": "object"
},
"AlertSummary": {
"description": "The alert fields shared by the list and detail reads (Postgres ``alerts``).\n\n``threshold`` is stored as a decimal and served as a JSON number.\n``creator`` is the created-by user's display name (or email), resolved by\nthe internal route; it is None when the creating account was deleted.",
"properties": {
"aggregation": {
"title": "Aggregation",
"type": "string"
},
"alerted_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Alerted At"
},
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"creator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creator"
},
"id": {
"title": "Id",
"type": "string"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_error_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error At"
},
"last_evaluated_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Evaluated At"
},
"last_notify_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify At"
},
"last_notify_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify Error"
},
"last_notify_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Notify Status"
},
"measure": {
"title": "Measure",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"severity": {
"title": "Severity",
"type": "string"
},
"severity_changed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Severity Changed At"
},
"status": {
"title": "Status",
"type": "string"
},
"threshold": {
"title": "Threshold",
"type": "number"
},
"threshold_operator": {
"title": "Threshold Operator",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
},
"view": {
"title": "View",
"type": "string"
},
"window": {
"title": "Window",
"type": "string"
}
},
"required": [
"id",
"name",
"view",
"measure",
"aggregation",
"window",
"threshold_operator",
"threshold",
"status",
"severity",
"severity_changed_at",
"alerted_at",
"last_evaluated_at",
"last_error",
"last_error_at",
"last_notify_status",
"last_notify_error",
"last_notify_at",
"create_time",
"update_time",
"creator"
],
"title": "AlertSummary",
"type": "object"
},
"CompleteRunRequest": {
"description": "Complete/fail a run, reporting final completeness counts.",
"properties": {
"case_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Case Count"
},
"scored_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Scored Count"
},
"scorer_error_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Scorer Error Count"
},
"scorers": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ScorerRef"
},
"maxItems": 200,
"type": "array"
},
{
"type": "null"
}
],
"title": "Scorers"
},
"status": {
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"title": "Status",
"type": "string"
},
"task_error_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Task Error Count"
}
},
"required": [
"status"
],
"title": "CompleteRunRequest",
"type": "object"
},
"CompleteRunResponse": {
"properties": {
"evaluation_run_id": {
"title": "Evaluation Run Id",
"type": "string"
},
"status": {
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"title": "Status",
"type": "string"
}
},
"required": [
"evaluation_run_id",
"status"
],
"title": "CompleteRunResponse",
"type": "object"
},
"CreateAlertRequest": {
"description": "Body for creating a threshold alert in a project.",
"properties": {
"aggregation": {
"enum": [
"sum",
"avg",
"count",
"max",
"min",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Aggregation",
"type": "string"
},
"filters": {
"description": "Row predicates the measure is evaluated over",
"items": {
"$ref": "#/components/schemas/AlertFilterItemRequest"
},
"title": "Filters",
"type": "array"
},
"measure": {
"description": "A measure of the view, e.g. latency, cost, count",
"title": "Measure",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"no_data_mode": {
"anyOf": [
{
"enum": [
"HOLD",
"ZERO",
"NOTIFY"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "What a window that measured nothing means; column default when omitted",
"title": "No Data Mode"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"renotify": {
"$ref": "#/components/schemas/AlertRenotifyRequest"
},
"threshold": {
"title": "Threshold",
"type": "number"
},
"threshold_operator": {
"enum": [
">",
">=",
"<",
"<=",
"=",
"!="
],
"title": "Threshold Operator",
"type": "string"
},
"view": {
"const": "SPANS",
"title": "View",
"type": "string"
},
"window": {
"enum": [
"1m",
"5m",
"10m",
"30m",
"1h",
"2h"
],
"title": "Window",
"type": "string"
}
},
"required": [
"project_id",
"name",
"view",
"measure",
"aggregation",
"window",
"threshold_operator",
"threshold",
"renotify"
],
"title": "CreateAlertRequest",
"type": "object"
},
"CreateAlertResponse": {
"description": "The created alert with its full rule (alert creation is strict, never idempotent).",
"properties": {
"alert": {
"$ref": "#/components/schemas/AlertDetail"
},
"created": {
"title": "Created",
"type": "boolean"
}
},
"required": [
"created",
"alert"
],
"title": "CreateAlertResponse",
"type": "object"
},
"CreateDashboardRequest": {
"description": "Body for creating a dashboard in a project.",
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
}
},
"required": [
"project_id",
"name"
],
"title": "CreateDashboardRequest",
"type": "object"
},
"CreateDashboardResponse": {
"description": "The created (or idempotently matched) dashboard.",
"properties": {
"created": {
"title": "Created",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
}
},
"required": [
"id",
"name",
"project_id",
"created"
],
"title": "CreateDashboardResponse",
"type": "object"
},
"CreateDetectorRequest": {
"description": "Body for creating a detector in a project.",
"properties": {
"detection_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Model"
},
"detection_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Provider"
},
"detection_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Source"
},
"enable_rca": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Rca"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled"
},
"name": {
"title": "Name",
"type": "string"
},
"output_schema": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Output Schema"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Detector instructions. Omit to adopt the canonical instructions of a standard template; required for any other template.",
"title": "Prompt"
},
"sample_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sample Rate"
},
"template": {
"title": "Template",
"type": "string"
},
"trigger_conditions": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"description": "Conditions gating WHICH completed traces the detector evaluates; omit or pass [] to evaluate every completed trace. Each condition is {field, op, value} (metadata also takes key): model_name/environment take =, !=; cost/total_tokens/duration_ms/errors take >, >=, <, <=, =; metadata takes =, contains. A condition is a deterministic pre-filter, not the flag decision - the prompt still judges every trace that passes.",
"title": "Trigger Conditions"
}
},
"required": [
"project_id",
"name",
"template"
],
"title": "CreateDetectorRequest",
"type": "object"
},
"CreateDetectorResponse": {
"description": "The created (or idempotently matched) detector.",
"properties": {
"created": {
"title": "Created",
"type": "boolean"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"sample_rate": {
"title": "Sample Rate",
"type": "integer"
}
},
"required": [
"id",
"name",
"project_id",
"enabled",
"sample_rate",
"created"
],
"title": "CreateDetectorResponse",
"type": "object"
},
"CreateProjectRequest": {
"description": "Body for creating a project inside a workspace.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"trace_ttl_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Trace Ttl Days"
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
}
},
"required": [
"workspace_id",
"name"
],
"title": "CreateProjectRequest",
"type": "object"
},
"CreateProjectResponse": {
"description": "The created (or idempotently matched) project.",
"properties": {
"created": {
"title": "Created",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
}
},
"required": [
"id",
"name",
"workspace_id",
"created"
],
"title": "CreateProjectResponse",
"type": "object"
},
"CreateWidgetRequest": {
"description": "Body for creating a widget on a dashboard.\n\nUnlike the other create bodies, ``spec`` is deep-validated here: it is a\nstructured contract the agent/CLI must compose (a wrong shape only\nsurfaces at render time otherwise), and the union below is what generated\ntool schemas show the model.",
"properties": {
"dashboard_id": {
"title": "Dashboard Id",
"type": "string"
},
"display_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Display Config"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"spec": {
"anyOf": [
{
"additionalProperties": false,
"description": "Chart spec over the \"spans\" view; the enums below are the complete field vocabulary for this view.",
"properties": {
"breakdown": {
"enum": [
"name",
"span_kind",
"error_type",
"model_name",
"environment",
null
],
"title": "Breakdown",
"type": [
"string",
"null"
]
},
"display": {
"additionalProperties": false,
"description": "Controls how the query result is rendered on the dashboard.",
"properties": {
"type": {
"enum": [
"line",
"area",
"bar",
"pie",
"number",
"table",
"histogram"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "WidgetDisplay",
"type": "object"
},
"filters": {
"items": {
"additionalProperties": false,
"description": "A single filter predicate applied to a widget query.",
"properties": {
"field": {
"enum": [
"name",
"span_kind",
"status",
"error_type",
"model_name",
"environment",
"is_root",
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"metadata"
],
"title": "Field",
"type": "string"
},
"key": {
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains",
"in",
">",
">=",
"<",
"<="
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
],
"title": "Value",
"type": [
"string",
"number",
"array"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "WidgetFilter",
"type": "object"
},
"title": "Filters",
"type": "array"
},
"metric": {
"additionalProperties": false,
"description": "The measure and aggregation function that define the widget's y-axis.",
"properties": {
"agg": {
"enum": [
"count",
"sum",
"avg",
"min",
"max",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Agg",
"type": "string"
},
"measure": {
"enum": [
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"tokens_per_second",
"trace_id",
"count"
],
"title": "Measure",
"type": "string"
}
},
"required": [
"measure",
"agg"
],
"title": "WidgetMetric",
"type": "object"
},
"view": {
"const": "spans",
"title": "View",
"type": "string"
}
},
"required": [
"view",
"metric",
"display"
],
"title": "WidgetSpec (spans)",
"type": "object"
},
{
"additionalProperties": false,
"description": "Chart spec over the \"traces\" view; the enums below are the complete field vocabulary for this view.",
"properties": {
"breakdown": {
"enum": [
"name",
"user_id",
"session_id",
"environment",
null
],
"title": "Breakdown",
"type": [
"string",
"null"
]
},
"display": {
"additionalProperties": false,
"description": "Controls how the query result is rendered on the dashboard.",
"properties": {
"type": {
"enum": [
"line",
"area",
"bar",
"pie",
"number",
"table",
"histogram"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "WidgetDisplay",
"type": "object"
},
"filters": {
"items": {
"additionalProperties": false,
"description": "A single filter predicate applied to a widget query.",
"properties": {
"field": {
"enum": [
"name",
"user_id",
"session_id",
"environment",
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"error_count"
],
"title": "Field",
"type": "string"
},
"key": {
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains",
"in",
">",
">=",
"<",
"<="
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
],
"title": "Value",
"type": [
"string",
"number",
"array"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "WidgetFilter",
"type": "object"
},
"title": "Filters",
"type": "array"
},
"metric": {
"additionalProperties": false,
"description": "The measure and aggregation function that define the widget's y-axis.",
"properties": {
"agg": {
"enum": [
"count",
"sum",
"avg",
"min",
"max",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Agg",
"type": "string"
},
"measure": {
"enum": [
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"count",
"error_count"
],
"title": "Measure",
"type": "string"
}
},
"required": [
"measure",
"agg"
],
"title": "WidgetMetric",
"type": "object"
},
"view": {
"const": "traces",
"title": "View",
"type": "string"
}
},
"required": [
"view",
"metric",
"display"
],
"title": "WidgetSpec (traces)",
"type": "object"
},
{
"$ref": "#/components/schemas/TraceFeedSpec"
}
],
"description": "The widget's content. For type \"query\": a chart spec (view/filters/metric/breakdown/display). For type \"trace_feed\": a trace-list feed spec (predicate filters + row limit).",
"title": "Spec"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"project_id",
"dashboard_id",
"title",
"type",
"spec"
],
"title": "CreateWidgetRequest",
"type": "object"
},
"CreateWidgetResponse": {
"description": "The created widget (widget creation is strict, never idempotent).",
"properties": {
"created": {
"title": "Created",
"type": "boolean"
},
"dashboard_id": {
"title": "Dashboard Id",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"dashboard_id",
"title",
"type",
"created"
],
"title": "CreateWidgetResponse",
"type": "object"
},
"CreateWorkspaceRequest": {
"description": "Body for creating a workspace the caller will administer.",
"properties": {
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "CreateWorkspaceRequest",
"type": "object"
},
"CreateWorkspaceResponse": {
"description": "The created (or idempotently matched) workspace.",
"properties": {
"created": {
"title": "Created",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"role": {
"title": "Role",
"type": "string"
}
},
"required": [
"id",
"name",
"role",
"created"
],
"title": "CreateWorkspaceResponse",
"type": "object"
},
"DashboardDataResponse": {
"description": "A dashboard's query widgets, up to the per-request cap, answered for one window.\n\nWidgets keep the dashboard's order. ``window`` is the window they were all\nanswered for \u2014 the one to name alongside any figure taken from here.\n``layout`` is the dashboard's grid placement, as ``get_dashboard`` returns\nit.",
"properties": {
"dashboard": {
"$ref": "#/components/schemas/DashboardSummary"
},
"failed": {
"title": "Failed",
"type": "integer"
},
"layout": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/DashboardLayoutItem"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Layout"
},
"queried": {
"title": "Queried",
"type": "integer"
},
"skipped": {
"title": "Skipped",
"type": "integer"
},
"widgets": {
"items": {
"$ref": "#/components/schemas/DashboardWidgetData"
},
"title": "Widgets",
"type": "array"
},
"window": {
"$ref": "#/components/schemas/QueryWindow"
}
},
"required": [
"dashboard",
"window",
"widgets",
"queried",
"skipped",
"failed"
],
"title": "DashboardDataResponse",
"type": "object"
},
"DashboardDetail": {
"description": "One dashboard with its widgets, ordered by creation time.\n\n``layout`` is the stored grid placement of the widgets that have one, or\nNone when the dashboard service did not report it.",
"properties": {
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"creator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creator"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"id": {
"title": "Id",
"type": "string"
},
"is_default": {
"title": "Is Default",
"type": "boolean"
},
"layout": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/DashboardLayoutItem"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Layout"
},
"name": {
"title": "Name",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
},
"widgets": {
"items": {
"$ref": "#/components/schemas/DashboardWidgetItem"
},
"title": "Widgets",
"type": "array"
}
},
"required": [
"id",
"name",
"description",
"is_default",
"creator",
"create_time",
"update_time",
"widgets"
],
"title": "DashboardDetail",
"type": "object"
},
"DashboardLayoutItem": {
"description": "One widget's place on a dashboard's grid, in grid units.\n\n``i`` is the widget id; ``x``/``w`` count columns of the twelve-column\ngrid and ``y``/``h`` count rows. A widget with no entry is placed by the\ndashboard page itself, below everything that has one.",
"properties": {
"h": {
"title": "H",
"type": "integer"
},
"i": {
"title": "I",
"type": "string"
},
"w": {
"title": "W",
"type": "integer"
},
"x": {
"title": "X",
"type": "integer"
},
"y": {
"title": "Y",
"type": "integer"
}
},
"required": [
"i",
"x",
"y",
"w",
"h"
],
"title": "DashboardLayoutItem",
"type": "object"
},
"DashboardListItem": {
"description": "A dashboard in the project's catalog (Postgres ``dashboards``).\n\n``id`` is the value ``create_widget`` takes as ``dashboard_id``.",
"properties": {
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"creator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creator"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"id": {
"title": "Id",
"type": "string"
},
"is_default": {
"title": "Is Default",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
},
"widget_count": {
"title": "Widget Count",
"type": "integer"
}
},
"required": [
"id",
"name",
"description",
"is_default",
"creator",
"create_time",
"update_time",
"widget_count"
],
"title": "DashboardListItem",
"type": "object"
},
"DashboardRow": {
"description": "A dashboard as the write service returns it.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
}
},
"required": [
"id",
"name",
"project_id"
],
"title": "DashboardRow",
"type": "object"
},
"DashboardSummary": {
"description": "The dashboard fields shared by the list and detail reads.\n\n``creator`` is the created-by user's display name (or email), resolved by\nthe internal route; it is None when the creating account was deleted.",
"properties": {
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"creator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creator"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"id": {
"title": "Id",
"type": "string"
},
"is_default": {
"title": "Is Default",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
}
},
"required": [
"id",
"name",
"description",
"is_default",
"creator",
"create_time",
"update_time"
],
"title": "DashboardSummary",
"type": "object"
},
"DashboardWidgetData": {
"description": "One widget's answer within a dashboard data read.\n\n``status`` says what happened: ``ok`` carries the engine's columns/rows/\nmeta (a series carries every bucket of the window; every other display's\nrows are capped, with ``truncated`` set when the cap bit); ``skipped``\nis a feed widget (a trace list, not an aggregate \u2014 read those with\n``list_traces`` and the feed's filters); ``error`` carries a short reason\nand no rows \u2014 a broken widget, or a query widget past the per-request cap\nwith a reason naming it \u2014 so neither fails the whole dashboard. ``spec``\nis the widget's stored spec whatever the status, so a caller can draw it.",
"properties": {
"columns": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Columns"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"id": {
"title": "Id",
"type": "string"
},
"meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta"
},
"rows": {
"anyOf": [
{
"items": {
"items": {},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Rows"
},
"spec": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Spec"
},
"status": {
"enum": [
"ok",
"skipped",
"error"
],
"title": "Status",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
},
"truncated": {
"default": false,
"title": "Truncated",
"type": "boolean"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"title",
"type",
"status"
],
"title": "DashboardWidgetData",
"type": "object"
},
"DashboardWidgetItem": {
"description": "A widget on a dashboard (Postgres ``widgets``).",
"properties": {
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"spec": {
"title": "Spec"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"title",
"type",
"spec",
"create_time"
],
"title": "DashboardWidgetItem",
"type": "object"
},
"DeleteAlertResponse": {
"description": "A hard-deleted alert; ``page_cleared`` reports an open page it discarded.",
"properties": {
"alert": {
"$ref": "#/components/schemas/DeletedResource"
},
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"page_cleared": {
"default": false,
"title": "Page Cleared",
"type": "boolean"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"deleted",
"reason",
"alert"
],
"title": "DeleteAlertResponse",
"type": "object"
},
"DeleteDashboardResponse": {
"description": "A hard-deleted dashboard and the count of widgets removed with it.",
"properties": {
"cascaded": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Cascaded"
},
"dashboard": {
"$ref": "#/components/schemas/DeletedResource"
},
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"deleted",
"reason",
"dashboard"
],
"title": "DeleteDashboardResponse",
"type": "object"
},
"DeleteDetectorResponse": {
"description": "A hard-deleted detector (its findings stay readable).",
"properties": {
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"detector": {
"$ref": "#/components/schemas/DeletedResource"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"deleted",
"reason",
"detector"
],
"title": "DeleteDetectorResponse",
"type": "object"
},
"DeleteProjectResponse": {
"description": "A soft-deleted project (its data stays for the retention window).",
"properties": {
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"project": {
"$ref": "#/components/schemas/DeletedResource"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"deleted",
"reason",
"project"
],
"title": "DeleteProjectResponse",
"type": "object"
},
"DeleteWidgetResponse": {
"description": "A hard-deleted widget (its layout entry is removed with it).",
"properties": {
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"reason": {
"title": "Reason",
"type": "string"
},
"widget": {
"$ref": "#/components/schemas/DeletedResource"
}
},
"required": [
"deleted",
"reason",
"widget"
],
"title": "DeleteWidgetResponse",
"type": "object"
},
"DeleteWorkspaceResponse": {
"description": "A hard-deleted workspace and the counts of what cascaded with it.",
"properties": {
"cascaded": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Cascaded"
},
"deleted": {
"title": "Deleted",
"type": "boolean"
},
"reason": {
"title": "Reason",
"type": "string"
},
"workspace": {
"$ref": "#/components/schemas/DeletedResource"
}
},
"required": [
"deleted",
"reason",
"workspace"
],
"title": "DeleteWorkspaceResponse",
"type": "object"
},
"DeletedResource": {
"description": "What a delete removed: the row's id and name, for the receipt.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"id",
"name"
],
"title": "DeletedResource",
"type": "object"
},
"DetectorDetail": {
"description": "A detector's full configuration (Postgres ``detectors`` + optional trigger).\n\n``trigger_conditions`` comes from ``detector_triggers.conditions`` and is\nNone when the detector has no trigger row (it then runs on every sampled\ntrace).",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"detection_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Model"
},
"detection_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Provider"
},
"detection_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Source"
},
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"enable_rca": {
"title": "Enable Rca",
"type": "boolean"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"output_schema": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Output Schema"
},
"prompt": {
"title": "Prompt",
"type": "string"
},
"sample_rate": {
"title": "Sample Rate",
"type": "integer"
},
"template": {
"title": "Template",
"type": "string"
},
"trigger_conditions": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Trigger Conditions"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"detector_id",
"name",
"template",
"enabled",
"created_at",
"prompt",
"output_schema",
"sample_rate",
"enable_rca",
"detection_model",
"detection_provider",
"detection_source",
"updated_at",
"trigger_conditions"
],
"title": "DetectorDetail",
"type": "object"
},
"DetectorItem": {
"description": "A detector from the project's catalog (Postgres ``detectors``).\n\n``detector_id`` is the value to pass to ``findings list --detector`` to filter\nfindings to this detector.",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"template": {
"title": "Template",
"type": "string"
}
},
"required": [
"detector_id",
"name",
"template",
"enabled",
"created_at"
],
"title": "DetectorItem",
"type": "object"
},
"DetectorResultItem": {
"description": "One detector's result within a finding, normalized from the stored payload.\n\nThe stored finding ``payload`` uses camelCase keys (``detectorId`` /\n``detectorName``); the public API exposes snake_case. Only triggered detectors\nare persisted, so ``identified`` is always ``True`` for a present item. ``data``\nis the detector's opaque output, passed through verbatim. ``template`` is looked\nup from the Postgres ``detectors`` row and is ``None`` when that row is absent\n(e.g. a deleted detector).",
"properties": {
"data": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Data"
},
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"detector_name": {
"title": "Detector Name",
"type": "string"
},
"identified": {
"title": "Identified",
"type": "boolean"
},
"signal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signal Id"
},
"signal_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signal Status"
},
"signal_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signal Title"
},
"summary": {
"title": "Summary",
"type": "string"
},
"template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template"
}
},
"required": [
"detector_id",
"detector_name",
"template",
"summary",
"identified",
"data"
],
"title": "DetectorResultItem",
"type": "object"
},
"DetectorRow": {
"description": "A detector as the write service returns it.",
"properties": {
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"sample_rate": {
"title": "Sample Rate",
"type": "integer"
}
},
"required": [
"id",
"name",
"project_id",
"enabled",
"sample_rate"
],
"title": "DetectorRow",
"type": "object"
},
"EmittedMetric": {
"description": "One metric a scorer DEFINITION emits, with its own comparison policy. The metric\n``name`` is the EMITTED-METRIC identity (what a Score row reports as ``scorer_name``),\ndistinct from the scorer DEFINITION name. Mirrors ``EmittedMetricSchema``.",
"properties": {
"direction": {
"anyOf": [
{
"enum": [
"higher_is_better",
"lower_is_better",
"none"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Direction"
},
"name": {
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Threshold"
},
"value_type": {
"anyOf": [
{
"enum": [
"numeric",
"boolean",
"categorical"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Value Type"
}
},
"required": [
"name"
],
"title": "EmittedMetric",
"type": "object"
},
"ErrorResponse": {
"description": "The canonical public error envelope (matches the gateway's normalized shape).",
"properties": {
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"detail"
],
"title": "ErrorResponse",
"type": "object"
},
"EvaluationLatestRun": {
"description": "An evaluation's most recent run, so a listing answers \"where does this stand?\".",
"properties": {
"evaluation_run_id": {
"title": "Evaluation Run Id",
"type": "string"
},
"run_number": {
"title": "Run Number",
"type": "integer"
},
"started_at": {
"title": "Started At",
"type": "string"
},
"status": {
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"title": "Status",
"type": "string"
}
},
"required": [
"evaluation_run_id",
"run_number",
"status",
"started_at"
],
"title": "EvaluationLatestRun",
"type": "object"
},
"ExportManifest": {
"description": "manifest.json: index of the bundle's parts.",
"properties": {
"bundle_version": {
"title": "Bundle Version",
"type": "string"
},
"files": {
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
}
},
"required": [
"trace_id",
"project_id",
"bundle_version",
"files"
],
"title": "ExportManifest",
"type": "object"
},
"FilterValueCount": {
"description": "A distinct categorical value and how often it occurs.",
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"value": {
"title": "Value",
"type": "string"
}
},
"required": [
"value",
"count"
],
"title": "FilterValueCount",
"type": "object"
},
"FilterValuesResponse": {
"description": "Distinct values for one categorical filter field, by frequency.",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"values": {
"items": {
"$ref": "#/components/schemas/FilterValueCount"
},
"title": "Values",
"type": "array"
}
},
"required": [
"field",
"values"
],
"title": "FilterValuesResponse",
"type": "object"
},
"FindingDetail": {
"description": "A finding plus its per-detector results and optional free-text RCA.",
"properties": {
"detectors": {
"items": {
"type": "string"
},
"title": "Detectors",
"type": "array"
},
"finding_id": {
"title": "Finding Id",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"rca": {
"anyOf": [
{
"$ref": "#/components/schemas/RCAResult"
},
{
"type": "null"
}
]
},
"results": {
"items": {
"$ref": "#/components/schemas/DetectorResultItem"
},
"title": "Results",
"type": "array"
},
"run_ids": {
"default": [],
"items": {
"type": "string"
},
"title": "Run Ids",
"type": "array"
},
"signals": {
"default": [],
"items": {
"$ref": "#/components/schemas/FindingSignal"
},
"title": "Signals",
"type": "array"
},
"summary": {
"title": "Summary",
"type": "string"
},
"timestamp": {
"format": "date-time",
"title": "Timestamp",
"type": "string"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
}
},
"required": [
"finding_id",
"project_id",
"trace_id",
"summary",
"timestamp",
"detectors",
"results",
"rca"
],
"title": "FindingDetail",
"type": "object"
},
"FindingSignal": {
"description": "The signal one detector's hit in a finding belongs to.",
"properties": {
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"signal_id": {
"title": "Signal Id",
"type": "string"
},
"signal_status": {
"title": "Signal Status",
"type": "string"
},
"signal_title": {
"title": "Signal Title",
"type": "string"
}
},
"required": [
"detector_id",
"signal_id",
"signal_title",
"signal_status"
],
"title": "FindingSignal",
"type": "object"
},
"FindingSummary": {
"description": "A detector finding row for the list view; ``detectors`` are display labels.",
"properties": {
"detectors": {
"items": {
"type": "string"
},
"title": "Detectors",
"type": "array"
},
"finding_id": {
"title": "Finding Id",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"run_ids": {
"default": [],
"items": {
"type": "string"
},
"title": "Run Ids",
"type": "array"
},
"signals": {
"default": [],
"items": {
"$ref": "#/components/schemas/FindingSignal"
},
"title": "Signals",
"type": "array"
},
"summary": {
"title": "Summary",
"type": "string"
},
"timestamp": {
"format": "date-time",
"title": "Timestamp",
"type": "string"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
}
},
"required": [
"finding_id",
"project_id",
"trace_id",
"summary",
"timestamp",
"detectors"
],
"title": "FindingSummary",
"type": "object"
},
"GetDatasetVersionResponse": {
"description": "A version snapshot: the version's identity plus a PAGE of its cases.",
"properties": {
"dataset_id": {
"title": "Dataset Id",
"type": "string"
},
"dataset_version_id": {
"title": "Dataset Version Id",
"type": "string"
},
"items": {
"items": {
"$ref": "#/components/schemas/PublicTestCase"
},
"title": "Items",
"type": "array"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
},
"version_number": {
"title": "Version Number",
"type": "integer"
}
},
"required": [
"dataset_version_id",
"dataset_id",
"version_number",
"label",
"items",
"next_cursor"
],
"title": "GetDatasetVersionResponse",
"type": "object"
},
"GitContext": {
"description": "git_context.json: repo/ref + per-span source locations.",
"properties": {
"git_ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Ref"
},
"git_repo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Repo"
},
"sources": {
"items": {
"$ref": "#/components/schemas/GitSource"
},
"title": "Sources",
"type": "array"
}
},
"required": [
"git_repo",
"git_ref",
"sources"
],
"title": "GitContext",
"type": "object"
},
"GitSource": {
"description": "A single span's source location (trace-resident git metadata).",
"properties": {
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"function": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Function"
},
"line": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Line"
},
"span_id": {
"title": "Span Id",
"type": "string"
}
},
"required": [
"span_id",
"file",
"line",
"function"
],
"title": "GitSource",
"type": "object"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
},
"IngestResponse": {
"description": "Response for trace ingestion.",
"properties": {
"file_key": {
"title": "File Key",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
}
},
"required": [
"status",
"file_key"
],
"title": "IngestResponse",
"type": "object"
},
"ListDatasetVersionsResponse": {
"properties": {
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
},
"versions": {
"items": {
"$ref": "#/components/schemas/PublicDatasetVersion"
},
"title": "Versions",
"type": "array"
}
},
"required": [
"versions",
"next_cursor"
],
"title": "ListDatasetVersionsResponse",
"type": "object"
},
"ListDatasetsResponse": {
"properties": {
"datasets": {
"items": {
"$ref": "#/components/schemas/PublicDataset"
},
"title": "Datasets",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
}
},
"required": [
"datasets",
"next_cursor"
],
"title": "ListDatasetsResponse",
"type": "object"
},
"ListEvaluationRunsResponse": {
"properties": {
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
},
"runs": {
"items": {
"$ref": "#/components/schemas/PublicEvaluationRun"
},
"title": "Runs",
"type": "array"
}
},
"required": [
"runs",
"next_cursor"
],
"title": "ListEvaluationRunsResponse",
"type": "object"
},
"ListEvaluationsResponse": {
"properties": {
"evaluations": {
"items": {
"$ref": "#/components/schemas/PublicEvaluation"
},
"title": "Evaluations",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
}
},
"required": [
"evaluations",
"next_cursor"
],
"title": "ListEvaluationsResponse",
"type": "object"
},
"PaginationMeta": {
"description": "Pagination metadata for list responses.",
"properties": {
"limit": {
"title": "Limit",
"type": "integer"
},
"page": {
"title": "Page",
"type": "integer"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"page",
"limit",
"total"
],
"title": "PaginationMeta",
"type": "object"
},
"ProjectListItem": {
"description": "A project the user can access, tagged with its owning workspace.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
},
"workspace_is_demo": {
"default": false,
"description": "True when the project is in the public demo workspace.",
"title": "Workspace Is Demo",
"type": "boolean"
},
"workspace_name": {
"title": "Workspace Name",
"type": "string"
}
},
"required": [
"id",
"name",
"workspace_id",
"workspace_name"
],
"title": "ProjectListItem",
"type": "object"
},
"ProjectRow": {
"description": "A project as the write service returns it.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
}
},
"required": [
"id",
"name",
"workspace_id"
],
"title": "ProjectRow",
"type": "object"
},
"PublicAlertListResponse": {
"description": "Paginated list of the project's alerts for the public API.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/AlertSummary"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/AlertListMeta"
}
},
"required": [
"data",
"meta"
],
"title": "PublicAlertListResponse",
"type": "object"
},
"PublicDashboardListResponse": {
"description": "The project's dashboards for the public API.\n\nNot paginated: a project's dashboard catalog is small and bounded.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/DashboardListItem"
},
"title": "Data",
"type": "array"
}
},
"required": [
"data"
],
"title": "PublicDashboardListResponse",
"type": "object"
},
"PublicDataset": {
"description": "A dataset as the public API describes it.\n\nEvery field is REQUIRED and nullable rather than optional: the route always emits all\nof them, and a default here would say the key may be absent, which is a different\ncontract from \"present and null\". The shape roster compares this to the Zod side\nfield-for-field, so the two cannot drift apart on that distinction.\n\n``dataset_id`` is the id a CLIENT addresses the dataset by \u2014 its own\n``client_dataset_id`` when it created the dataset, or the row id for one authored in\nthe UI. ``key`` is the pre-image of that id, so a pulled dataset recovers its key when\nkey and name differ.\n\nNo case count: no dataset read computes one, and deriving it would need an N+1 over\nversions. It lives on a version, where it is one grouped aggregate.",
"properties": {
"current_dataset_version_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Current Dataset Version Id"
},
"dataset_id": {
"title": "Dataset Id",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Key"
},
"name": {
"title": "Name",
"type": "string"
},
"updated_at": {
"title": "Updated At",
"type": "string"
}
},
"required": [
"dataset_id",
"name",
"description",
"current_dataset_version_id",
"key",
"updated_at"
],
"title": "PublicDataset",
"type": "object"
},
"PublicDatasetVersion": {
"properties": {
"case_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Case Count",
"type": "integer"
},
"created_at": {
"title": "Created At",
"type": "string"
},
"dataset_version_id": {
"title": "Dataset Version Id",
"type": "string"
},
"is_current": {
"title": "Is Current",
"type": "boolean"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"version_number": {
"title": "Version Number",
"type": "integer"
}
},
"required": [
"dataset_version_id",
"version_number",
"label",
"note",
"case_count",
"created_at",
"is_current"
],
"title": "PublicDatasetVersion",
"type": "object"
},
"PublicDetectorListResponse": {
"description": "Paginated list of the project's detectors for the public API.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/DetectorItem"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
},
"required": [
"data",
"meta"
],
"title": "PublicDetectorListResponse",
"type": "object"
},
"PublicEvaluation": {
"description": "One evaluation lineage: a stable purpose, re-run over time.\n\nIdentity and counts only. Scores belong to a run \u2014 a lineage has no single headline\nscore, and averaging across runs would invent one.",
"properties": {
"created_at": {
"title": "Created At",
"type": "string"
},
"dataset_id": {
"title": "Dataset Id",
"type": "string"
},
"evaluation_id": {
"title": "Evaluation Id",
"type": "string"
},
"evaluation_key": {
"title": "Evaluation Key",
"type": "string"
},
"latest_run": {
"anyOf": [
{
"$ref": "#/components/schemas/EvaluationLatestRun"
},
{
"type": "null"
}
]
},
"name": {
"title": "Name",
"type": "string"
},
"run_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Run Count",
"type": "integer"
},
"updated_at": {
"title": "Updated At",
"type": "string"
}
},
"required": [
"evaluation_id",
"name",
"evaluation_key",
"dataset_id",
"run_count",
"latest_run",
"created_at",
"updated_at"
],
"title": "PublicEvaluation",
"type": "object"
},
"PublicEvaluationRun": {
"description": "One run as the LISTING reports it: identity, where it ran, and how it ended.\n\nNo counts, means, cost or duration. Those are aggregates over a run's results, so a page\nof runs would be a page of aggregate queries; the run read answers them one run at a\ntime.",
"properties": {
"candidate_version": {
"title": "Candidate Version",
"type": "string"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"dataset_id": {
"title": "Dataset Id",
"type": "string"
},
"dataset_version_id": {
"title": "Dataset Version Id",
"type": "string"
},
"environment": {
"title": "Environment",
"type": "string"
},
"evaluation_id": {
"title": "Evaluation Id",
"type": "string"
},
"evaluation_key": {
"title": "Evaluation Key",
"type": "string"
},
"evaluation_name": {
"title": "Evaluation Name",
"type": "string"
},
"evaluation_run_id": {
"title": "Evaluation Run Id",
"type": "string"
},
"run_number": {
"title": "Run Number",
"type": "integer"
},
"started_at": {
"title": "Started At",
"type": "string"
},
"status": {
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"title": "Status",
"type": "string"
}
},
"required": [
"evaluation_run_id",
"evaluation_id",
"evaluation_name",
"evaluation_key",
"run_number",
"candidate_version",
"environment",
"status",
"dataset_id",
"dataset_version_id",
"started_at",
"completed_at"
],
"title": "PublicEvaluationRun",
"type": "object"
},
"PublicFindingListResponse": {
"description": "Paginated list of detector findings for the public API.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/FindingSummary"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
},
"required": [
"data",
"meta"
],
"title": "PublicFindingListResponse",
"type": "object"
},
"PublicProjectListResponse": {
"description": "Account-scope discovery: the projects the user can access.\n\nReturned by ``list_projects`` \u2014 a user-credential-only op. Projects are\nflattened across the user's workspaces; an optional ``workspace_id`` query\nnarrows the result to one workspace.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/ProjectListItem"
},
"title": "Data",
"type": "array"
}
},
"required": [
"data"
],
"title": "PublicProjectListResponse",
"type": "object"
},
"PublicSignalListResponse": {
"description": "Paginated list of the project's signals for the public API (newest first).",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/SignalSummary"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
},
"required": [
"data",
"meta"
],
"title": "PublicSignalListResponse",
"type": "object"
},
"PublicTestCase": {
"description": "One test case in a version snapshot.\n\n``input``/``expected``/``metadata`` are NATIVE JSON values \u2014 an object stays an\nobject, a JSON-looking string stays a string \u2014 so they are ``Any``, not ``str``.",
"properties": {
"expected": {
"title": "Expected"
},
"input": {
"title": "Input"
},
"metadata": {
"title": "Metadata"
},
"source_span_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Span Id"
},
"source_trace_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Trace Id"
},
"test_case_id": {
"title": "Test Case Id",
"type": "string"
}
},
"required": [
"test_case_id",
"input",
"expected",
"metadata",
"source_trace_id",
"source_span_id"
],
"title": "PublicTestCase",
"type": "object"
},
"PublicTraceDetailResponse": {
"description": "Full trace payload plus a backend-built link to its UI detail view.",
"properties": {
"git_ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Ref"
},
"git_repo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Repo"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Input"
},
"metadata": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"name": {
"title": "Name",
"type": "string"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Output"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
},
"spans": {
"items": {
"$ref": "#/components/schemas/SpanResponse"
},
"title": "Spans",
"type": "array"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
},
"trace_start_time": {
"format": "date-time",
"title": "Trace Start Time",
"type": "string"
},
"trace_url": {
"title": "Trace Url",
"type": "string"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
"required": [
"trace_id",
"project_id",
"name",
"trace_start_time",
"user_id",
"session_id",
"git_ref",
"git_repo",
"input",
"output",
"metadata",
"spans",
"trace_url"
],
"title": "PublicTraceDetailResponse",
"type": "object"
},
"PublicTraceExportResponse": {
"description": "V1 export bundle: trace (== `traces get`) + spans + git_context + manifest.",
"properties": {
"git_context": {
"$ref": "#/components/schemas/GitContext"
},
"manifest": {
"$ref": "#/components/schemas/ExportManifest"
},
"spans": {
"items": {
"$ref": "#/components/schemas/SpanResponse"
},
"title": "Spans",
"type": "array"
},
"trace": {
"$ref": "#/components/schemas/PublicTraceDetailResponse"
}
},
"required": [
"manifest",
"trace",
"spans",
"git_context"
],
"title": "PublicTraceExportResponse",
"type": "object"
},
"PublicTraceListItem": {
"description": "A trace list item plus a backend-built link to its UI detail view.",
"properties": {
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"error_count": {
"title": "Error Count",
"type": "integer"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Input"
},
"metadata_map": {
"additionalProperties": {
"type": "string"
},
"default": {},
"title": "Metadata Map",
"type": "object"
},
"name": {
"title": "Name",
"type": "string"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Output"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
},
"span_count": {
"title": "Span Count",
"type": "integer"
},
"total_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 0.0,
"title": "Total Cost"
},
"total_input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": 0,
"title": "Total Input Tokens"
},
"total_output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": 0,
"title": "Total Output Tokens"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
},
"trace_start_time": {
"format": "date-time",
"title": "Trace Start Time",
"type": "string"
},
"trace_url": {
"title": "Trace Url",
"type": "string"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
"required": [
"trace_id",
"project_id",
"name",
"trace_start_time",
"user_id",
"session_id",
"span_count",
"duration_ms",
"error_count",
"input",
"output",
"trace_url"
],
"title": "PublicTraceListItem",
"type": "object"
},
"PublicTraceListResponse": {
"description": "Paginated list of traces for the public API.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/PublicTraceListItem"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
},
"required": [
"data",
"meta"
],
"title": "PublicTraceListResponse",
"type": "object"
},
"PublicWorkspaceListResponse": {
"description": "Account-scope discovery: the workspaces the user can access.\n\nReturned by ``list_workspaces`` \u2014 a user-credential-only op that needs no\n``project_id``. Not paginated: a user's workspace membership is small and\nbounded.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/WorkspaceListItem"
},
"title": "Data",
"type": "array"
}
},
"required": [
"data"
],
"title": "PublicWorkspaceListResponse",
"type": "object"
},
"QueryWindow": {
"description": "The window a query was actually answered for.\n\n``range`` is the preset id the caller gave (or the default's, when they\ngave nothing) and None for explicit bounds. ``clamped`` is True when the\nplan's retention pulled ``start_time`` forward \u2014 the honest reason a\ncaller's window and the answered one differ.",
"properties": {
"clamped": {
"title": "Clamped",
"type": "boolean"
},
"end_time": {
"format": "date-time",
"title": "End Time",
"type": "string"
},
"range": {
"anyOf": [
{
"enum": [
"30m",
"1h",
"3h",
"6h",
"1d",
"7d",
"14d",
"30d",
"60d",
"90d"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Range"
},
"start_time": {
"format": "date-time",
"title": "Start Time",
"type": "string"
}
},
"required": [
"start_time",
"end_time",
"range",
"clamped"
],
"title": "QueryWindow",
"type": "object"
},
"RCAResult": {
"description": "Free-text root-cause analysis for a finding (Postgres ``detector_rcas``).\n\nThe agent trace behind an RCA (``detector_rca_executions``) is internal and\ndeliberately not part of this contract: its trace id is not readable through\nthe public trace endpoints, so advertising it here would be misleading.",
"properties": {
"inherited": {
"default": false,
"title": "Inherited",
"type": "boolean"
},
"result": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Result"
},
"status": {
"title": "Status",
"type": "string"
}
},
"required": [
"status",
"result"
],
"title": "RCAResult",
"type": "object"
},
"ReadRunResponse": {
"description": "A run's SUMMARY \u2014 deliberately no per-case rows, so the payload is bounded by\nscorer count rather than case count and needs no truncation flag.",
"properties": {
"candidate_version": {
"title": "Candidate Version",
"type": "string"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"dataset_id": {
"title": "Dataset Id",
"type": "string"
},
"dataset_version_id": {
"title": "Dataset Version Id",
"type": "string"
},
"environment": {
"title": "Environment",
"type": "string"
},
"errored_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Errored Count",
"type": "integer"
},
"evaluation_id": {
"title": "Evaluation Id",
"type": "string"
},
"evaluation_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Evaluation Key"
},
"evaluation_name": {
"title": "Evaluation Name",
"type": "string"
},
"evaluation_run_id": {
"title": "Evaluation Run Id",
"type": "string"
},
"failed_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Failed Count",
"type": "integer"
},
"metrics": {
"items": {
"$ref": "#/components/schemas/RunMetricItem"
},
"title": "Metrics",
"type": "array"
},
"not_scored_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Not Scored Count",
"type": "integer"
},
"passed_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Passed Count",
"type": "integer"
},
"result_count": {
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Result Count",
"type": "integer"
},
"run_number": {
"title": "Run Number",
"type": "integer"
},
"run_path": {
"title": "Run Path",
"type": "string"
},
"run_url": {
"title": "Run Url",
"type": "string"
},
"scored_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Scored Count"
},
"scorer_error_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Scorer Error Count"
},
"scores": {
"items": {
"$ref": "#/components/schemas/RunMetricItem"
},
"title": "Scores",
"type": "array"
},
"started_at": {
"title": "Started At",
"type": "string"
},
"status": {
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"title": "Status",
"type": "string"
},
"task_error_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Task Error Count"
}
},
"required": [
"evaluation_run_id",
"evaluation_id",
"evaluation_name",
"run_number",
"candidate_version",
"environment",
"status",
"started_at",
"dataset_id",
"dataset_version_id",
"run_path",
"run_url",
"result_count",
"scored_count",
"task_error_count",
"scorer_error_count",
"passed_count",
"failed_count",
"errored_count",
"not_scored_count"
],
"title": "ReadRunResponse",
"type": "object"
},
"RegisterRunRequest": {
"description": "Register/start a run. Idempotent on ``client_run_id`` within an evaluation.",
"properties": {
"baseline_run_id": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Baseline Run Id"
},
"candidate_version": {
"maxLength": 200,
"minLength": 1,
"title": "Candidate Version",
"type": "string"
},
"case_count": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Case Count"
},
"client_run_id": {
"anyOf": [
{
"maxLength": 128,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Client Run Id"
},
"dataset_id": {
"maxLength": 64,
"minLength": 1,
"title": "Dataset Id",
"type": "string"
},
"dataset_version_id": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Dataset Version Id"
},
"environment": {
"default": "evaluation",
"maxLength": 64,
"minLength": 1,
"title": "Environment",
"type": "string"
},
"evaluation_key": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Evaluation Key"
},
"evaluation_name": {
"maxLength": 200,
"minLength": 1,
"title": "Evaluation Name",
"type": "string"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"scorers": {
"items": {
"$ref": "#/components/schemas/ScorerRef"
},
"maxItems": 200,
"title": "Scorers",
"type": "array"
}
},
"required": [
"evaluation_name",
"dataset_id",
"candidate_version"
],
"title": "RegisterRunRequest",
"type": "object"
},
"RegisterRunResponse": {
"properties": {
"dataset_version_id": {
"title": "Dataset Version Id",
"type": "string"
},
"evaluation_id": {
"title": "Evaluation Id",
"type": "string"
},
"evaluation_run_id": {
"title": "Evaluation Run Id",
"type": "string"
},
"run_number": {
"title": "Run Number",
"type": "integer"
},
"run_path": {
"title": "Run Path",
"type": "string"
},
"run_url": {
"title": "Run Url",
"type": "string"
}
},
"required": [
"evaluation_id",
"evaluation_run_id",
"run_number",
"dataset_version_id",
"run_path",
"run_url"
],
"title": "RegisterRunResponse",
"type": "object"
},
"RunMetricItem": {
"description": "One score or one derived metric. Identical shape for both: they differ in\nPROVENANCE (a scorer reported it vs the platform derived it from the trace), not in\nstructure, and a client renders them the same way.\n\n``value`` is the run's own mean over ``observed_count`` results, and null rather than\n0 when nothing was observed \u2014 \"no data\" and \"measured zero\" are different facts and\nmust stay distinguishable.",
"properties": {
"direction": {
"enum": [
"higher_is_better",
"lower_is_better",
"none"
],
"title": "Direction",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"observed_count": {
"description": "How many results reported a usable value for this score or metric.",
"maximum": 9007199254740991.0,
"minimum": 0.0,
"title": "Observed Count",
"type": "integer"
},
"unit": {
"anyOf": [
{
"enum": [
"$",
"tok",
"ms",
"count"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "The run's own mean over observed_count results. Null when nothing was observed, and always for a categorical score or one that stored labels and numbers together.",
"title": "Value"
},
"value_type": {
"description": "The scorer's declared kind, else the kind it stored. Every derived metric is numeric.",
"enum": [
"numeric",
"boolean",
"categorical"
],
"title": "Value Type",
"type": "string"
}
},
"required": [
"name",
"direction",
"value_type",
"observed_count"
],
"title": "RunMetricItem",
"type": "object"
},
"ScoreInput": {
"description": "One scorer's outcome on one result. ``error`` set = the scorer failed to judge.",
"properties": {
"bool_value": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Bool Value"
},
"error": {
"anyOf": [
{
"maxLength": 5000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"explanation": {
"anyOf": [
{
"maxLength": 5000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Explanation"
},
"numeric_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Numeric Value"
},
"passed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Passed"
},
"scorer_name": {
"maxLength": 200,
"minLength": 1,
"title": "Scorer Name",
"type": "string"
},
"scorer_version": {
"maxLength": 50,
"minLength": 1,
"title": "Scorer Version",
"type": "string"
},
"string_value": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"title": "String Value"
}
},
"required": [
"scorer_name",
"scorer_version"
],
"title": "ScoreInput",
"type": "object"
},
"ScorerMessage": {
"description": "One prompt message of an LLM-judge scorer's definition.",
"properties": {
"content": {
"maxLength": 20000,
"title": "Content",
"type": "string"
},
"role": {
"maxLength": 50,
"minLength": 1,
"title": "Role",
"type": "string"
}
},
"required": [
"role",
"content"
],
"title": "ScorerMessage",
"type": "object"
},
"ScorerRef": {
"description": "A scorer's descriptor. ``key`` is the stable SEMANTIC comparison identity\n(it defaults to ``name`` when omitted \u2014 see below); ``name``/``version``/\n``language``/``source`` are provenance, NOT identity. The richer metadata is\noptional and back-compatible (an old SDK sending only ``{name, version}`` stays\nvalid \u2014 its ``key`` falls back to ``name``). Mirrors the non-strict\n``ScorerRefSchema``, so unknown keys are ignored rather than rejected.\n\nThe DEFINITION fields (``scorer_type``, prompt/source, config) let the read-only\nScorer detail render an LLM judge's model + messages or a code scorer's snippet.\n\n``scorer_type`` / ``output_type`` / ``language`` are display-only, so an\nunrecognised value from a newer SDK degrades to ``None`` rather than failing\nrun registration (which would lose the run's every result and score) \u2014\nmatching ``.catch(null)`` on the Zod side. The vocabularies that drive\npersistence and aggregation still reject.",
"properties": {
"description": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"direction": {
"anyOf": [
{
"enum": [
"higher_is_better",
"lower_is_better",
"none"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Direction"
},
"emitted_metrics": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/EmittedMetric"
},
"maxItems": 20,
"type": "array"
},
{
"type": "null"
}
],
"title": "Emitted Metrics"
},
"key": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Key"
},
"language": {
"anyOf": [
{
"enum": [
"python",
"typescript"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Language"
},
"messages": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ScorerMessage"
},
"maxItems": 50,
"type": "array"
},
{
"type": "null"
}
],
"title": "Messages"
},
"metadata": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Metadata"
},
"model": {
"anyOf": [
{
"maxLength": 200,
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"name": {
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
},
"output_type": {
"anyOf": [
{
"enum": [
"score",
"classification"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Output Type"
},
"required_inputs": {
"anyOf": [
{
"items": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"maxItems": 20,
"type": "array"
},
{
"type": "null"
}
],
"title": "Required Inputs"
},
"scorer_type": {
"anyOf": [
{
"enum": [
"llm_judge",
"code"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Scorer Type"
},
"source": {
"anyOf": [
{
"maxLength": 50000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Threshold"
},
"value_type": {
"anyOf": [
{
"enum": [
"numeric",
"boolean",
"categorical"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Value Type"
},
"version": {
"maxLength": 50,
"minLength": 1,
"title": "Version",
"type": "string"
}
},
"required": [
"name",
"version"
],
"title": "ScorerRef",
"type": "object"
},
"SessionDetailResponse": {
"description": "Session detail with all traces for conversation view.",
"properties": {
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"first_trace_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "First Trace Time"
},
"last_trace_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Trace Time"
},
"session_id": {
"title": "Session Id",
"type": "string"
},
"total_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Cost"
},
"total_input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Input Tokens"
},
"total_output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Output Tokens"
},
"trace_count": {
"title": "Trace Count",
"type": "integer"
},
"traces": {
"items": {
"$ref": "#/components/schemas/SessionTraceItem"
},
"title": "Traces",
"type": "array"
},
"user_ids": {
"items": {
"type": "string"
},
"title": "User Ids",
"type": "array"
}
},
"required": [
"session_id",
"traces",
"user_ids",
"trace_count",
"first_trace_time",
"last_trace_time",
"duration_ms",
"total_input_tokens",
"total_output_tokens"
],
"title": "SessionDetailResponse",
"type": "object"
},
"SessionListItem": {
"description": "Single session with aggregated trace statistics.",
"properties": {
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"first_trace_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "First Trace Time"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Input"
},
"last_trace_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Trace Time"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Output"
},
"session_id": {
"title": "Session Id",
"type": "string"
},
"total_cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Cost"
},
"total_input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Input Tokens"
},
"total_output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Output Tokens"
},
"trace_count": {
"title": "Trace Count",
"type": "integer"
},
"user_ids": {
"items": {
"type": "string"
},
"title": "User Ids",
"type": "array"
}
},
"required": [
"session_id",
"trace_count",
"user_ids",
"first_trace_time",
"last_trace_time",
"duration_ms",
"total_input_tokens",
"total_output_tokens",
"input",
"output"
],
"title": "SessionListItem",
"type": "object"
},
"SessionListResponse": {
"description": "Paginated list of sessions.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/SessionListItem"
},
"title": "Data",
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
},
"required": [
"data",
"meta"
],
"title": "SessionListResponse",
"type": "object"
},
"SessionTraceItem": {
"description": "Single trace within a session, for conversation view.",
"properties": {
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Input"
},
"name": {
"title": "Name",
"type": "string"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Output"
},
"status": {
"title": "Status",
"type": "string"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
},
"trace_start_time": {
"format": "date-time",
"title": "Trace Start Time",
"type": "string"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
"required": [
"trace_id",
"name",
"trace_start_time",
"user_id",
"input",
"output",
"duration_ms",
"status"
],
"title": "SessionTraceItem",
"type": "object"
},
"SignalDetail": {
"description": "One signal, including when it was resolved and whether it was merged.\n\nA merged signal is still answered, with ``merged_into_id`` naming the signal\nits findings moved to; lists leave merged signals out.",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"detector_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detector Name"
},
"first_seen_at": {
"format": "date-time",
"title": "First Seen At",
"type": "string"
},
"hit_count": {
"title": "Hit Count",
"type": "integer"
},
"last_seen_at": {
"format": "date-time",
"title": "Last Seen At",
"type": "string"
},
"merged_into_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Merged Into Id"
},
"rca_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rca State"
},
"reopen_count": {
"title": "Reopen Count",
"type": "integer"
},
"resolved_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Resolved At"
},
"signal_id": {
"title": "Signal Id",
"type": "string"
},
"status": {
"enum": [
"open",
"resolved",
"dismissed"
],
"title": "Status",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"signal_id",
"detector_id",
"detector_name",
"title",
"status",
"hit_count",
"reopen_count",
"first_seen_at",
"last_seen_at",
"created_at",
"resolved_at",
"merged_into_id"
],
"title": "SignalDetail",
"type": "object"
},
"SignalStatusRequest": {
"additionalProperties": false,
"description": "Body for resolving or reopening a signal.\n\nOnly ``resolved`` and ``open`` are settable here. A dismissed signal never\nreopens on a new finding, so dismissing stays a decision a person makes in\nthe web app. Resolving needs a ``reason``; the reason ``other`` also needs\na ``note``. The write service is the single validator of those rules.",
"properties": {
"expected_status": {
"description": "The status the caller last read. When the signal's current status differs, nothing is written and the answer is a 409.",
"enum": [
"open",
"resolved",
"dismissed"
],
"title": "Expected Status",
"type": "string"
},
"note": {
"description": "A free-text note; required when reason is \"other\"",
"maxLength": 4000,
"title": "Note",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"reason": {
"description": "Why the signal is resolved; required when status is \"resolved\"",
"enum": [
"fixed_elsewhere",
"fixed_by_pr",
"already_fixed_before",
"other"
],
"title": "Reason",
"type": "string"
},
"status": {
"enum": [
"resolved",
"open"
],
"title": "Status",
"type": "string"
}
},
"required": [
"project_id",
"status"
],
"title": "SignalStatusRequest",
"type": "object"
},
"SignalStatusResponse": {
"description": "The signal after the write. ``changed`` is empty when it already had that status.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"signal": {
"$ref": "#/components/schemas/SignalStatusRow"
},
"updated": {
"title": "Updated",
"type": "boolean"
}
},
"required": [
"updated",
"changed",
"signal"
],
"title": "SignalStatusResponse",
"type": "object"
},
"SignalStatusRow": {
"description": "A signal as the status write returns it.",
"properties": {
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"reopen_count": {
"title": "Reopen Count",
"type": "integer"
},
"resolved_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"format": "date-time",
"title": "Resolved At"
},
"signal_id": {
"title": "Signal Id",
"type": "string"
},
"status": {
"enum": [
"open",
"resolved",
"dismissed"
],
"title": "Status",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"signal_id",
"project_id",
"detector_id",
"title",
"status",
"resolved_at",
"reopen_count"
],
"title": "SignalStatusRow",
"type": "object"
},
"SignalSummary": {
"description": "A signal: a recurring problem that one detector's findings are grouped into.\n\n``reopen_count`` counts the automatic reopens (a new finding after the\nsignal was resolved). ``rca_state`` is the state of the root cause analysis\nof the current opening, null when none ran for it.",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"detector_id": {
"title": "Detector Id",
"type": "string"
},
"detector_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detector Name"
},
"first_seen_at": {
"format": "date-time",
"title": "First Seen At",
"type": "string"
},
"hit_count": {
"title": "Hit Count",
"type": "integer"
},
"last_seen_at": {
"format": "date-time",
"title": "Last Seen At",
"type": "string"
},
"rca_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rca State"
},
"reopen_count": {
"title": "Reopen Count",
"type": "integer"
},
"signal_id": {
"title": "Signal Id",
"type": "string"
},
"status": {
"enum": [
"open",
"resolved",
"dismissed"
],
"title": "Status",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"signal_id",
"detector_id",
"detector_name",
"title",
"status",
"hit_count",
"reopen_count",
"first_seen_at",
"last_seen_at",
"created_at"
],
"title": "SignalSummary",
"type": "object"
},
"SpanResponse": {
"description": "A span skeleton plus its per-span I/O blobs (``input``/``output``/``metadata``).\n\nThe projection-capable superset returned by the trace get/export endpoints.\nThe blobs default to ``None`` and are populated only when the caller requests\nthe matching field group (``io``/``metadata``; see\n``rest.projection``). The default ``skeleton`` projection leaves them ``None``\nand never runs the bulk span-I/O query, so there is no payload or query-cost\nregression for the dashboard. Keeping the fields present (as ``null``) rather\nthan omitting them is additive: a few bytes per span, and it matches the\nfields the shipped CLI's generated types already declare.\n\nOne internal-only exception: the dashboard's trace-detail read leaves a small\nSDK span-path subset in ``metadata`` on the skeleton, which it needs to\nrebuild the tree of an in-flight trace. The public routes drop it (see\n``rest.projection.drop_span_tree_metadata``), so for API clients the contract\nabove holds exactly: ``metadata`` is ``null`` unless requested.",
"properties": {
"cost": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Cost"
},
"cost_details": {
"additionalProperties": {
"type": "number"
},
"default": {},
"title": "Cost Details",
"type": "object"
},
"error_type": {
"default": "",
"title": "Error Type",
"type": "string"
},
"git_source_file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Source File"
},
"git_source_function": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Source Function"
},
"git_source_line": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Git Source Line"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Input"
},
"input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Input Tokens"
},
"metadata": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"model_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model Name"
},
"name": {
"title": "Name",
"type": "string"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Output"
},
"output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Output Tokens"
},
"parent_span_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Span Id"
},
"span_end_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Span End Time"
},
"span_id": {
"title": "Span Id",
"type": "string"
},
"span_kind": {
"title": "Span Kind",
"type": "string"
},
"span_start_time": {
"format": "date-time",
"title": "Span Start Time",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
},
"status_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status Message"
},
"total_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Tokens"
},
"trace_id": {
"title": "Trace Id",
"type": "string"
},
"usage_details": {
"additionalProperties": {
"type": "integer"
},
"default": {},
"title": "Usage Details",
"type": "object"
}
},
"required": [
"span_id",
"trace_id",
"parent_span_id",
"name",
"span_kind",
"span_start_time",
"span_end_time",
"status",
"status_message",
"model_name",
"cost",
"input_tokens",
"output_tokens",
"total_tokens"
],
"title": "SpanResponse",
"type": "object"
},
"SqlColumn": {
"description": "One column of a result, named and typed as ClickHouse reported it.\n\nA result with no rows carries no metadata from the driver, so the service\nasks the server to describe the statement it just ran. Either way the name\nand the type are the server's own, so neither is ever absent.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"name",
"type"
],
"title": "SqlColumn",
"type": "object"
},
"SqlRequest": {
"additionalProperties": false,
"description": "A public SQL query. The project is never part of this body.\n\n``extra=\"forbid\"`` is the point rather than tidiness: scope is resolved from\nthe credential, so a body carrying ``project_id`` or a ``scope_*`` key is a\ncaller trying to choose a tenant. Forbidding unknown keys turns that into a\n422 instead of a silently ignored field.",
"properties": {
"max_rows": {
"anyOf": [
{
"maximum": 1000000.0,
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Rows to return, clamped down to the server ceiling",
"title": "Max Rows"
},
"parameters": {
"anyOf": [
{
"additionalProperties": true,
"maxProperties": 100,
"type": "object"
},
{
"type": "null"
}
],
"description": "Values for {name:Type} placeholders in the query",
"title": "Parameters"
},
"query": {
"description": "A single read-only SELECT over the public schema",
"maxLength": 65536,
"minLength": 1,
"title": "Query",
"type": "string"
}
},
"required": [
"query"
],
"title": "SqlRequest",
"type": "object"
},
"SqlResponse": {
"description": "A completed query, already trimmed to what the caller may receive.",
"properties": {
"columns": {
"items": {
"$ref": "#/components/schemas/SqlColumn"
},
"title": "Columns",
"type": "array"
},
"elapsed_ms": {
"title": "Elapsed Ms",
"type": "integer"
},
"row_count": {
"title": "Row Count",
"type": "integer"
},
"rows": {
"items": {
"items": {},
"type": "array"
},
"title": "Rows",
"type": "array"
},
"statistics": {
"additionalProperties": true,
"title": "Statistics",
"type": "object"
},
"truncated": {
"description": "True when more rows matched than were returned",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"columns",
"rows",
"row_count",
"truncated",
"elapsed_ms"
],
"title": "SqlResponse",
"type": "object"
},
"SqlSchemaColumn": {
"description": "A curated column a caller may select.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"name",
"type"
],
"title": "SqlSchemaColumn",
"type": "object"
},
"SqlSchemaResponse": {
"description": "The curated analytical schema, which is all a caller can query.",
"properties": {
"tables": {
"items": {
"$ref": "#/components/schemas/SqlSchemaTable"
},
"title": "Tables",
"type": "array"
}
},
"required": [
"tables"
],
"title": "SqlSchemaResponse",
"type": "object"
},
"SqlSchemaTable": {
"description": "A logical table the gateway exposes.",
"properties": {
"columns": {
"items": {
"$ref": "#/components/schemas/SqlSchemaColumn"
},
"title": "Columns",
"type": "array"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name",
"columns"
],
"title": "SqlSchemaTable",
"type": "object"
},
"TraceFeedInPredicate": {
"additionalProperties": false,
"description": "Membership predicate: the field's value is one of the listed strings.",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"key": {
"maxLength": 256,
"minLength": 1,
"title": "Key",
"type": "string"
},
"op": {
"const": "in",
"title": "Op",
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"title": "Value",
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"title": "TraceFeedInPredicate",
"type": "object"
},
"TraceFeedNumericPredicate": {
"additionalProperties": false,
"description": "Numeric comparison predicate (equality or ordering) on a finite number.",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"key": {
"maxLength": 256,
"minLength": 1,
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte"
],
"title": "Op",
"type": "string"
},
"value": {
"title": "Value",
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"title": "TraceFeedNumericPredicate",
"type": "object"
},
"TraceFeedSpec": {
"additionalProperties": false,
"description": "Spec for a ``trace_feed`` widget: a filtered live list of recent traces.\n\nMirrors the trace-list predicate wire format (canonical shape: what\n``isValidPredicate`` in frontend/ui/src/features/filters/predicate.ts\naccepts and the dashboard seed produces). ``limit`` carries the trace-list\npage-size bound; it defaults to 10 rows in the renderer when omitted.",
"properties": {
"filters": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TraceFeedInPredicate"
},
{
"$ref": "#/components/schemas/TraceFeedNumericPredicate"
},
{
"$ref": "#/components/schemas/TraceFeedTextPredicate"
}
]
},
"maxItems": 20,
"title": "Filters",
"type": "array"
},
"limit": {
"maximum": 200.0,
"minimum": 1.0,
"title": "Limit",
"type": "integer"
}
},
"title": "TraceFeedSpec",
"type": "object"
},
"TraceFeedTextPredicate": {
"additionalProperties": false,
"description": "Text predicate: exact match or substring containment.",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"key": {
"maxLength": 256,
"minLength": 1,
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"eq",
"contains"
],
"title": "Op",
"type": "string"
},
"value": {
"maxLength": 1024,
"minLength": 1,
"title": "Value",
"type": "string"
}
},
"required": [
"field",
"op",
"value"
],
"title": "TraceFeedTextPredicate",
"type": "object"
},
"UpdateAlertRequest": {
"additionalProperties": false,
"description": "Body for editing an alert rule (the ten rule fields, all optional).\n\nThe write service validates the patch merged with the stored rule; an\nedit to any evaluated field resets the evaluation state (and clears an\nopen page), which the response reports. Status has its own route.",
"properties": {
"aggregation": {
"enum": [
"sum",
"avg",
"count",
"max",
"min",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Aggregation",
"type": "string"
},
"filters": {
"description": "Row predicates the measure is evaluated over",
"items": {
"$ref": "#/components/schemas/AlertFilterItemRequest"
},
"title": "Filters",
"type": "array"
},
"measure": {
"description": "A measure of the view, e.g. latency, cost, count",
"title": "Measure",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"no_data_mode": {
"description": "What a window that measured nothing means",
"enum": [
"HOLD",
"ZERO",
"NOTIFY"
],
"title": "No Data Mode",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"renotify": {
"$ref": "#/components/schemas/AlertRenotifyRequest",
"title": "Renotify"
},
"threshold": {
"title": "Threshold",
"type": "number"
},
"threshold_operator": {
"enum": [
">",
">=",
"<",
"<=",
"=",
"!="
],
"title": "Threshold Operator",
"type": "string"
},
"view": {
"const": "SPANS",
"title": "View",
"type": "string"
},
"window": {
"enum": [
"1m",
"5m",
"10m",
"30m",
"1h",
"2h"
],
"title": "Window",
"type": "string"
}
},
"required": [
"project_id"
],
"title": "UpdateAlertRequest",
"type": "object"
},
"UpdateAlertResponse": {
"description": "The updated alert with its full rule, plus what the edit did to its state.",
"properties": {
"alert": {
"$ref": "#/components/schemas/AlertDetail"
},
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"page_cleared": {
"default": false,
"description": "True when the alert was firing and the edit discarded that page",
"title": "Page Cleared",
"type": "boolean"
},
"state_reset": {
"default": false,
"description": "True when the edit voided the evaluation state and made the rule due now (any evaluated field changed, or the alert was resumed)",
"title": "State Reset",
"type": "boolean"
},
"updated": {
"title": "Updated",
"type": "boolean"
}
},
"required": [
"updated",
"changed",
"alert"
],
"title": "UpdateAlertResponse",
"type": "object"
},
"UpdateDashboardRequest": {
"additionalProperties": false,
"description": "Body for editing a dashboard's name or description (layout stays UI-only).",
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "null clears the description",
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
}
},
"required": [
"project_id"
],
"title": "UpdateDashboardRequest",
"type": "object"
},
"UpdateDashboardResponse": {
"description": "The updated dashboard.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"dashboard": {
"$ref": "#/components/schemas/DashboardRow"
},
"updated": {
"title": "Updated",
"type": "boolean"
}
},
"required": [
"updated",
"changed",
"dashboard"
],
"title": "UpdateDashboardResponse",
"type": "object"
},
"UpdateDetectorRequest": {
"additionalProperties": false,
"description": "Body for editing a detector; ``template`` is immutable and not accepted.",
"properties": {
"detection_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Model"
},
"detection_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Provider"
},
"detection_source": {
"anyOf": [
{
"enum": [
"system",
"byok"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Detection Source"
},
"enable_rca": {
"title": "Enable Rca",
"type": "boolean"
},
"enabled": {
"description": "The pause switch. Detection is ingestion-triggered, so enabling starts nothing retroactively.",
"title": "Enabled",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"output_schema": {
"description": "Replaces the whole output schema array",
"items": {},
"title": "Output Schema",
"type": "array"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"prompt": {
"description": "Detector instructions, stored verbatim. There is no reset to a template's default on update: send the canonical text to restore it.",
"title": "Prompt",
"type": "string"
},
"sample_rate": {
"title": "Sample Rate",
"type": "integer"
},
"trigger_conditions": {
"description": "Replaces the whole trigger array; [] removes the trigger so every completed trace is evaluated. Each condition is {field, op, value} (metadata also takes key): model_name/environment take =, !=; cost/total_tokens/duration_ms/errors take >, >=, <, <=, =; metadata takes =, contains.",
"items": {},
"title": "Trigger Conditions",
"type": "array"
}
},
"required": [
"project_id"
],
"title": "UpdateDetectorRequest",
"type": "object"
},
"UpdateDetectorResponse": {
"description": "The updated detector.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"detector": {
"$ref": "#/components/schemas/DetectorRow"
},
"updated": {
"title": "Updated",
"type": "boolean"
}
},
"required": [
"updated",
"changed",
"detector"
],
"title": "UpdateDetectorResponse",
"type": "object"
},
"UpdateProjectRequest": {
"additionalProperties": false,
"description": "Body for editing a project (requires ADMIN in its workspace).",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"trace_ttl_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Trace retention in days (1-365); null returns to the plan default",
"title": "Trace Ttl Days"
}
},
"title": "UpdateProjectRequest",
"type": "object"
},
"UpdateProjectResponse": {
"description": "The updated project.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"project": {
"$ref": "#/components/schemas/ProjectRow"
},
"updated": {
"title": "Updated",
"type": "boolean"
}
},
"required": [
"updated",
"changed",
"project"
],
"title": "UpdateProjectResponse",
"type": "object"
},
"UpdateWidgetRequest": {
"additionalProperties": false,
"description": "Body for editing a widget; ``type`` and ``dashboard_id`` are immutable.",
"properties": {
"display_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Replaces the whole display config; null resets it to {}",
"title": "Display Config"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"spec": {
"anyOf": [
{
"additionalProperties": false,
"description": "Chart spec over the \"spans\" view; the enums below are the complete field vocabulary for this view.",
"properties": {
"breakdown": {
"enum": [
"name",
"span_kind",
"error_type",
"model_name",
"environment",
null
],
"title": "Breakdown",
"type": [
"string",
"null"
]
},
"display": {
"additionalProperties": false,
"description": "Controls how the query result is rendered on the dashboard.",
"properties": {
"type": {
"enum": [
"line",
"area",
"bar",
"pie",
"number",
"table",
"histogram"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "WidgetDisplay",
"type": "object"
},
"filters": {
"items": {
"additionalProperties": false,
"description": "A single filter predicate applied to a widget query.",
"properties": {
"field": {
"enum": [
"name",
"span_kind",
"status",
"error_type",
"model_name",
"environment",
"is_root",
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"metadata"
],
"title": "Field",
"type": "string"
},
"key": {
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains",
"in",
">",
">=",
"<",
"<="
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
],
"title": "Value",
"type": [
"string",
"number",
"array"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "WidgetFilter",
"type": "object"
},
"title": "Filters",
"type": "array"
},
"metric": {
"additionalProperties": false,
"description": "The measure and aggregation function that define the widget's y-axis.",
"properties": {
"agg": {
"enum": [
"count",
"sum",
"avg",
"min",
"max",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Agg",
"type": "string"
},
"measure": {
"enum": [
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"tokens_per_second",
"trace_id",
"count"
],
"title": "Measure",
"type": "string"
}
},
"required": [
"measure",
"agg"
],
"title": "WidgetMetric",
"type": "object"
},
"view": {
"const": "spans",
"title": "View",
"type": "string"
}
},
"required": [
"view",
"metric",
"display"
],
"title": "WidgetSpec (spans)",
"type": "object"
},
{
"additionalProperties": false,
"description": "Chart spec over the \"traces\" view; the enums below are the complete field vocabulary for this view.",
"properties": {
"breakdown": {
"enum": [
"name",
"user_id",
"session_id",
"environment",
null
],
"title": "Breakdown",
"type": [
"string",
"null"
]
},
"display": {
"additionalProperties": false,
"description": "Controls how the query result is rendered on the dashboard.",
"properties": {
"type": {
"enum": [
"line",
"area",
"bar",
"pie",
"number",
"table",
"histogram"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "WidgetDisplay",
"type": "object"
},
"filters": {
"items": {
"additionalProperties": false,
"description": "A single filter predicate applied to a widget query.",
"properties": {
"field": {
"enum": [
"name",
"user_id",
"session_id",
"environment",
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"error_count"
],
"title": "Field",
"type": "string"
},
"key": {
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains",
"in",
">",
">=",
"<",
"<="
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
],
"title": "Value",
"type": [
"string",
"number",
"array"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "WidgetFilter",
"type": "object"
},
"title": "Filters",
"type": "array"
},
"metric": {
"additionalProperties": false,
"description": "The measure and aggregation function that define the widget's y-axis.",
"properties": {
"agg": {
"enum": [
"count",
"sum",
"avg",
"min",
"max",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Agg",
"type": "string"
},
"measure": {
"enum": [
"duration_ms",
"cost",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"total_tokens",
"count",
"error_count"
],
"title": "Measure",
"type": "string"
}
},
"required": [
"measure",
"agg"
],
"title": "WidgetMetric",
"type": "object"
},
"view": {
"const": "traces",
"title": "View",
"type": "string"
}
},
"required": [
"view",
"metric",
"display"
],
"title": "WidgetSpec (traces)",
"type": "object"
},
{
"$ref": "#/components/schemas/TraceFeedSpec"
}
],
"description": "Replaces the whole spec, in the dialect of the widget's stored type. For type \"query\": a chart spec (view/filters/metric/breakdown/display). For type \"trace_feed\": a trace-list feed spec (predicate filters + row limit).",
"title": "Spec"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"project_id"
],
"title": "UpdateWidgetRequest",
"type": "object"
},
"UpdateWidgetResponse": {
"description": "The updated widget.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"updated": {
"title": "Updated",
"type": "boolean"
},
"widget": {
"$ref": "#/components/schemas/WidgetRow"
}
},
"required": [
"updated",
"changed",
"widget"
],
"title": "UpdateWidgetResponse",
"type": "object"
},
"UpdateWorkspaceRequest": {
"additionalProperties": false,
"description": "Body for renaming a workspace the caller administers.",
"properties": {
"name": {
"title": "Name",
"type": "string"
}
},
"title": "UpdateWorkspaceRequest",
"type": "object"
},
"UpdateWorkspaceResponse": {
"description": "The updated workspace.",
"properties": {
"changed": {
"items": {
"type": "string"
},
"title": "Changed",
"type": "array"
},
"updated": {
"title": "Updated",
"type": "boolean"
},
"workspace": {
"$ref": "#/components/schemas/WorkspaceRow"
}
},
"required": [
"updated",
"changed",
"workspace"
],
"title": "UpdateWorkspaceResponse",
"type": "object"
},
"UpsertResultRequest": {
"description": "Upsert one test-case result. Idempotent on (``run_id``, ``test_case_id``).\n``trace_id`` may be null now and set on a later call (out-of-order arrival).\n\n``scores`` is genuinely optional and carries three distinct meanings, so the\nout-of-order flow (POST the result with its scores, then re-POST later just to\nattach the OTel ``trace_id``) cannot destroy them: absent \u2192 leave the existing\nscores untouched, ``[]`` \u2192 clear them, non-empty \u2192 replace them. Do not give\nthis a ``default_factory=list``, which would collapse the first two cases.\n\nEvery optional field is a *partial* update: a key the caller omits keeps its\nstored value, while an explicit null clears it. Sending ``scores`` replaces\nthe result's scores (``[]`` clears them); omitting it leaves them alone.",
"properties": {
"baseline_output": {
"anyOf": [
{
"maxLength": 1000000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Baseline Output"
},
"candidate_output": {
"anyOf": [
{
"maxLength": 1000000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Candidate Output"
},
"change": {
"anyOf": [
{
"enum": [
"improved",
"regressed",
"unchanged"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Change"
},
"cost": {
"anyOf": [
{
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Cost"
},
"duration_ms": {
"anyOf": [
{
"maximum": 9007199254740991.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"expected_output": {
"anyOf": [
{
"maxLength": 1000000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Expected Output"
},
"input": {
"maxLength": 1000000,
"title": "Input",
"type": "string"
},
"scores": {
"items": {
"$ref": "#/components/schemas/ScoreInput"
},
"maxItems": 200,
"title": "Scores",
"type": "array"
},
"status": {
"enum": [
"passed",
"failed",
"errored",
"not_scored"
],
"title": "Status",
"type": "string"
},
"task_error": {
"anyOf": [
{
"maxLength": 10000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Task Error"
},
"test_case_id": {
"maxLength": 64,
"minLength": 1,
"title": "Test Case Id",
"type": "string"
},
"trace_id": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Trace Id"
}
},
"required": [
"test_case_id",
"input",
"status"
],
"title": "UpsertResultRequest",
"type": "object"
},
"UpsertResultResponse": {
"properties": {
"evaluation_result_id": {
"title": "Evaluation Result Id",
"type": "string"
}
},
"required": [
"evaluation_result_id"
],
"title": "UpsertResultResponse",
"type": "object"
},
"ValidationError": {
"properties": {
"ctx": {
"title": "Context",
"type": "object"
},
"input": {
"title": "Input"
},
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Location",
"type": "array"
},
"msg": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Error Type",
"type": "string"
}
},
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError",
"type": "object"
},
"WhoamiResponse": {
"description": "Identity a project API key resolves to, for `login` / `status`.\n\nName fields are nullable: they depend on what the internal key-validation\ncontract returns, and the backend never fabricates them. The full API token\nis never included \u2014 only ``key_hint``.\n\n``key_scope`` is the exception to the nullability above, deliberately. A\nholder asking what their key may do needs an answer, not a maybe: a null\nwould have to be handled by every caller and would mean the same thing the\nnarrow scope already means. It is a closed set of values rather than a free\nstring so a client can exhaust it.",
"properties": {
"host": {
"title": "Host",
"type": "string"
},
"key_hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Key Hint"
},
"key_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Key Name"
},
"key_scope": {
"enum": [
"ingest",
"admin"
],
"title": "Key Scope",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"project_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Name"
},
"ui_base_url": {
"title": "Ui Base Url",
"type": "string"
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
},
"workspace_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Workspace Name"
}
},
"required": [
"project_id",
"project_name",
"workspace_id",
"workspace_name",
"key_name",
"key_hint",
"key_scope",
"host",
"ui_base_url"
],
"title": "WhoamiResponse",
"type": "object"
},
"WidgetDataResponse": {
"description": "One saved widget answered for one window.\n\nThe per-widget answer of a dashboard data read, addressed by widget id:\n``status`` says what happened \u2014 ``ok`` carries the engine's columns/rows/\nmeta; ``skipped`` is a feed or legacy detector widget (a trace list, not\nan aggregate \u2014 read those with ``list_traces`` and the feed's filters);\n``error`` carries a short reason and no rows when the stored spec no\nlonger validates or the engine rejects it \u2014 so a broken widget is still a\n200 a script can branch on. One widget has no fan-out to protect, so the\nrows follow ``run_widget_query``: a series comes back whole and every\nother display returns what the engine returns. ``truncated`` is kept for\nparity with the dashboard read and is always false here. ``window`` is\nthe window the rows were answered for \u2014 the one to name with any figure.",
"properties": {
"columns": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Columns"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"meta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta"
},
"rows": {
"anyOf": [
{
"items": {
"items": {},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Rows"
},
"status": {
"enum": [
"ok",
"skipped",
"error"
],
"title": "Status",
"type": "string"
},
"truncated": {
"default": false,
"title": "Truncated",
"type": "boolean"
},
"widget": {
"$ref": "#/components/schemas/WidgetRef"
},
"window": {
"$ref": "#/components/schemas/QueryWindow"
}
},
"required": [
"widget",
"window",
"status"
],
"title": "WidgetDataResponse",
"type": "object"
},
"WidgetDetail": {
"description": "One saved widget, as stored, with the dashboard it belongs to.\n\n``spec`` is exactly what the create parsed (defaults filled, unknown keys\nstripped), so what a caller reads is what the engine runs. ``dashboard_id``\nand ``dashboard_name`` let a caller holding only a widget id climb to the\ndashboard without a second read. Widgets record no creator.",
"properties": {
"create_time": {
"format": "date-time",
"title": "Create Time",
"type": "string"
},
"dashboard_id": {
"title": "Dashboard Id",
"type": "string"
},
"dashboard_name": {
"title": "Dashboard Name",
"type": "string"
},
"display_config": {
"title": "Display Config"
},
"id": {
"title": "Id",
"type": "string"
},
"spec": {
"title": "Spec"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
},
"update_time": {
"format": "date-time",
"title": "Update Time",
"type": "string"
}
},
"required": [
"id",
"title",
"type",
"spec",
"create_time",
"dashboard_id",
"dashboard_name",
"display_config",
"update_time"
],
"title": "WidgetDetail",
"type": "object"
},
"WidgetDisplay": {
"additionalProperties": false,
"description": "Controls how the query result is rendered on the dashboard.",
"properties": {
"type": {
"enum": [
"line",
"area",
"bar",
"pie",
"number",
"table",
"histogram"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "WidgetDisplay",
"type": "object"
},
"WidgetFilter": {
"additionalProperties": false,
"description": "A single filter predicate applied to a widget query.",
"properties": {
"field": {
"title": "Field",
"type": "string"
},
"key": {
"title": "Key",
"type": "string"
},
"op": {
"enum": [
"=",
"contains",
"in",
">",
">=",
"<",
"<="
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
],
"title": "Value",
"type": [
"string",
"number",
"array"
]
}
},
"required": [
"field",
"op",
"value"
],
"title": "WidgetFilter",
"type": "object"
},
"WidgetMetric": {
"additionalProperties": false,
"description": "The measure and aggregation function that define the widget's y-axis.",
"properties": {
"agg": {
"enum": [
"count",
"sum",
"avg",
"min",
"max",
"p50",
"p75",
"p90",
"p95",
"p99",
"uniq"
],
"title": "Agg",
"type": "string"
},
"measure": {
"title": "Measure",
"type": "string"
}
},
"required": [
"measure",
"agg"
],
"title": "WidgetMetric",
"type": "object"
},
"WidgetQueryRequest": {
"additionalProperties": false,
"description": "Envelope that pairs a WidgetSpec with the time window to answer it for.\n\nThe window is either a ``range`` preset (the site picker's ids \u2014 how the\nagent and the CLI describe one) or explicit ``start_time``/``end_time``\n(how the dashboard page and the card previews do). Neither means the\nsite's default window; both, or one bound alone, is rejected. The rules\nlive in ``rest.services.date_presets.resolve_window`` so every query\nsurface applies the same ones.",
"properties": {
"bucket_seconds": {
"anyOf": [
{
"maximum": 86400.0,
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bucket Seconds"
},
"end_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
},
"range": {
"anyOf": [
{
"enum": [
"30m",
"1h",
"3h",
"6h",
"1d",
"7d",
"14d",
"30d",
"60d",
"90d"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.",
"title": "Range"
},
"spec": {
"$ref": "#/components/schemas/WidgetSpec"
},
"start_time": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
}
},
"required": [
"spec"
],
"title": "WidgetQueryRequest",
"type": "object"
},
"WidgetQueryResponse": {
"description": "Query result returned to the frontend; meta carries display hints (e.g. granularity for time-series displays).",
"properties": {
"columns": {
"items": {
"type": "string"
},
"title": "Columns",
"type": "array"
},
"meta": {
"additionalProperties": true,
"title": "Meta",
"type": "object"
},
"rows": {
"items": {
"items": {},
"type": "array"
},
"title": "Rows",
"type": "array"
},
"window": {
"$ref": "#/components/schemas/QueryWindow"
}
},
"required": [
"columns",
"rows",
"window"
],
"title": "WidgetQueryResponse",
"type": "object"
},
"WidgetRef": {
"description": "The identity of the widget a data read answered, with its dashboard.\n\n``spec`` is the stored spec the read ran, as ``get_widget`` returns it.",
"properties": {
"dashboard_id": {
"title": "Dashboard Id",
"type": "string"
},
"dashboard_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Dashboard Name"
},
"id": {
"title": "Id",
"type": "string"
},
"spec": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Spec"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"dashboard_id",
"title",
"type"
],
"title": "WidgetRef",
"type": "object"
},
"WidgetRow": {
"description": "A widget as the write service returns it.",
"properties": {
"dashboard_id": {
"title": "Dashboard Id",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"dashboard_id",
"title",
"type"
],
"title": "WidgetRow",
"type": "object"
},
"WidgetSpec": {
"additionalProperties": false,
"description": "Full declarative specification of a single dashboard widget.\n\nMirrors the canonical zod ``WidgetSpecSchema``\n(frontend/ui/src/features/dashboards/types.ts); the frontend\nwidget-spec-parity test guards the two against structural drift.",
"properties": {
"breakdown": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Breakdown"
},
"display": {
"$ref": "#/components/schemas/WidgetDisplay"
},
"filters": {
"items": {
"$ref": "#/components/schemas/WidgetFilter"
},
"title": "Filters",
"type": "array"
},
"metric": {
"$ref": "#/components/schemas/WidgetMetric"
},
"view": {
"enum": [
"spans",
"traces"
],
"title": "View",
"type": "string"
}
},
"required": [
"view",
"metric",
"display"
],
"title": "WidgetSpec",
"type": "object"
},
"WorkspaceListItem": {
"description": "A workspace the authenticated user belongs to, with their role in it.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"is_demo": {
"default": false,
"description": "True for the public demo workspace, which every user can read. It is listed last and is not one of the user's own workspaces.",
"title": "Is Demo",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"role": {
"title": "Role",
"type": "string"
}
},
"required": [
"id",
"name",
"role"
],
"title": "WorkspaceListItem",
"type": "object"
},
"WorkspaceRow": {
"description": "A workspace as the write service returns it: id, name, the caller's role.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"role": {
"title": "Role",
"type": "string"
}
},
"required": [
"id",
"name",
"role"
],
"title": "WorkspaceRow",
"type": "object"
}
},
"securitySchemes": {
"BearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"title": "TraceRoot Public API",
"version": "0.1.0"
},
"openapi": "3.1.0",
"paths": {
"/api/v1/public/alerts": {
"get": {
"description": "List the alerts in the caller's project (oldest first) with its capacity.",
"operationId": "list_alerts",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "0-based page index",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 0,
"description": "0-based page index",
"maximum": 10000,
"minimum": 0,
"title": "Page",
"type": "integer"
}
},
{
"description": "Case-insensitive substring match on the alert name",
"in": "query",
"name": "search_query",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 200,
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring match on the alert name",
"title": "Search Query"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicAlertListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Alerts",
"tags": [
"Alerts"
],
"x-tool": {
"description": "List the project's threshold alerts (id, name, rule summary, status, current severity, last evaluation and notification state, creator) with the project's alert capacity. Paginated; search_query matches the alert name. To resolve an alert by name, list here and match its name \u2014 never guess an alert id.",
"enabled": true,
"name": "list_alerts"
}
},
"post": {
"description": "Create a threshold alert in a project the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Strict create \u2014 alerts have no unique name, so every\ncall inserts and ``created`` is always ``true`` on success.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateAlertRequest): The alert rule to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateAlertResponse: The created alert with its full rule.",
"operationId": "create_alert",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAlertRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAlertResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The project has reached its alert limit"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create an alert",
"tags": [
"Alerts"
],
"x-tool": {
"description": "Create a threshold alert in a project: a measure of the spans view, aggregated over a window and compared to a threshold, with optional row filters and renotify/no-data settings. Strict create, never idempotent: alerts share names freely, so to avoid a duplicate list the project's alerts first and match the name.",
"enabled": true,
"name": "create_alert",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/alerts/{alert_id}": {
"delete": {
"description": "Hard-delete an alert.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). An outstanding page is discarded, not resolved: the\nresponse reports ``page_cleared`` when one was open.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n alert_id (str): The alert to delete.\n project_id (str): The project the alert belongs to.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteAlertResponse: The removed alert and whether a page was cleared.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "delete_alert",
"parameters": [
{
"in": "path",
"name": "alert_id",
"required": true,
"schema": {
"title": "Alert Id",
"type": "string"
}
},
{
"description": "The project the resource belongs to",
"in": "query",
"name": "project_id",
"required": true,
"schema": {
"description": "The project the resource belongs to",
"title": "Project Id",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteAlertResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete an alert",
"tags": [
"Alerts"
],
"x-tool": {
"description": "Permanently delete an alert. An open page is discarded, not resolved (the response says when one was). Requires a reason (3-500 characters) stating why \u2014 the user's actual instruction, recorded on the audit row. Resolve the id by listing the project's alerts and matching the name; never delete more than the user named.",
"enabled": true,
"name": "delete_alert",
"policy": {
"approvalClass": "approval",
"minRole": "MEMBER",
"tenancy": "project"
}
}
},
"get": {
"description": "Get one alert with its full rule for the caller's project.",
"operationId": "get_alert",
"parameters": [
{
"in": "path",
"name": "alert_id",
"required": true,
"schema": {
"title": "Alert Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Alert not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Alert",
"tags": [
"Alerts"
],
"x-tool": {
"description": "Fetch one alert's full rule by id: view, measure, aggregation, filters, window, threshold, renotify and no-data handling, plus its evaluation state. Resolve the alert id by listing the project's alerts and matching the name \u2014 never guess an id.",
"enabled": true,
"name": "get_alert"
}
},
"patch": {
"description": "Edit an alert's rule in a project the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). The patch is validated merged with the stored rule; an\nedit to any evaluated field resets the evaluation state, clears an open\npage, and re-arms a parked alert \u2014 the response reports the first two.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n alert_id (str): The alert to edit.\n payload (UpdateAlertRequest): The project and the rule fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateAlertResponse: The updated alert, the changed fields, and the\n state flags.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "update_alert",
"parameters": [
{
"in": "path",
"name": "alert_id",
"required": true,
"schema": {
"title": "Alert Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAlertRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAlertResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Edit an alert rule",
"tags": [
"Alerts"
],
"x-tool": {
"description": "Edit an alert's rule: name, view, measure, aggregation, filters, window, threshold_operator, threshold, renotify, no_data_mode. Fields left out are untouched; the patch is validated against the stored rule, so an aggregation edit must fit the stored measure. Any edit to an evaluated field (everything but name) resets the alert's evaluation state and clears any open page \u2014 the response reports state_reset and page_cleared, and lists the fields that actually changed. To pause or resume, use set_alert_status instead.",
"enabled": true,
"name": "update_alert",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/alerts/{alert_id}/status": {
"patch": {
"description": "Pause or resume an alert without touching its rule.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Pausing keeps the severity it stopped at; resuming is a\ncold start (state reset, due now). Setting the status the alert already\nhas is a 200 with nothing changed.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n alert_id (str): The alert to pause or resume.\n payload (AlertStatusRequest): The project and the target status.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateAlertResponse: The alert with its new status and the state flags.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "set_alert_status",
"parameters": [
{
"in": "path",
"name": "alert_id",
"required": true,
"schema": {
"title": "Alert Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertStatusRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAlertResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "A parked alert cannot be paused; resume it to run it again"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Pause or resume an alert",
"tags": [
"Alerts"
],
"x-tool": {
"description": "Pause (PAUSED) or resume (ACTIVE) an alert without touching its rule \u2014 prefer this over update_alert for pause and resume. Pausing keeps the severity the alert stopped at; resuming is a cold start (evaluation state reset, due now). PARKED is the evaluator's verdict and cannot be requested; pausing a parked alert is a conflict, resume it to run it again. Setting the status the alert already has changes nothing.",
"enabled": true,
"name": "set_alert_status",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/dashboards": {
"get": {
"description": "List the dashboards in the caller's project (default first).",
"operationId": "list_dashboards",
"parameters": [
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicDashboardListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Dashboards",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "List the project's dashboards (id, name, description, default flag, creator, widget count, timestamps). To resolve a dashboard by name, list here and match its name \u2014 never guess a dashboard id.",
"enabled": true,
"name": "list_dashboards"
}
},
"post": {
"description": "Create a dashboard in a project the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Idempotent on the dashboard name within the project.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateDashboardRequest): The dashboard to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateDashboardResponse: The created (or matched) dashboard.",
"operationId": "create_dashboard",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDashboardRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDashboardResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create a dashboard",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "Create a dashboard in a project (idempotent on the dashboard name within the project); add charts to it with create_widget.",
"enabled": true,
"name": "create_dashboard",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/dashboards/{dashboard_id}": {
"delete": {
"description": "Hard-delete a dashboard together with its widgets.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). A project's last dashboard cannot be deleted.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n dashboard_id (str): The dashboard to delete.\n project_id (str): The project the dashboard belongs to.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteDashboardResponse: The removed dashboard and its widget count.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "delete_dashboard",
"parameters": [
{
"in": "path",
"name": "dashboard_id",
"required": true,
"schema": {
"title": "Dashboard Id",
"type": "string"
}
},
{
"description": "The project the resource belongs to",
"in": "query",
"name": "project_id",
"required": true,
"schema": {
"description": "The project the resource belongs to",
"title": "Project Id",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteDashboardResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Cannot delete a project's last dashboard"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete a dashboard",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "Permanently delete a dashboard together with its widgets. A project's last dashboard cannot be deleted. Requires a reason (3-500 characters) stating why \u2014 the user's actual instruction, recorded on the audit row. Resolve the id by listing the project's dashboards and matching the name; never delete more than the user named.",
"enabled": true,
"name": "delete_dashboard",
"policy": {
"approvalClass": "approval",
"minRole": "MEMBER",
"tenancy": "project"
}
}
},
"get": {
"description": "Get one dashboard with its widgets for the caller's project.",
"operationId": "get_dashboard",
"parameters": [
{
"in": "path",
"name": "dashboard_id",
"required": true,
"schema": {
"title": "Dashboard Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DashboardDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Dashboard not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Dashboard",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "Fetch one dashboard with its widgets (id, title, type, query spec, creation time). Resolve the dashboard id by listing the project's dashboards and matching the name \u2014 never guess an id.",
"enabled": true,
"name": "get_dashboard"
}
},
"patch": {
"description": "Edit a dashboard's name or description.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). A null ``description`` clears it.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n dashboard_id (str): The dashboard to edit.\n payload (UpdateDashboardRequest): The project and the fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateDashboardResponse: The updated dashboard and the changed fields.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "update_dashboard",
"parameters": [
{
"in": "path",
"name": "dashboard_id",
"required": true,
"schema": {
"title": "Dashboard Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDashboardRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDashboardResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Name already in use"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Edit a dashboard",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "Rename a dashboard or change its description. Fields left out are untouched; a null description clears it. Tile layout is not editable here. The response lists the fields that actually changed.",
"enabled": true,
"name": "update_dashboard",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/dashboards/{dashboard_id}/data": {
"get": {
"description": "Answer one dashboard's query widgets, up to the per-request cap, for a window.",
"operationId": "get_dashboard_data",
"parameters": [
{
"in": "path",
"name": "dashboard_id",
"required": true,
"schema": {
"title": "Dashboard Id",
"type": "string"
}
},
{
"description": "A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.",
"in": "query",
"name": "range",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"30m",
"1h",
"3h",
"6h",
"1d",
"7d",
"14d",
"30d",
"60d",
"90d"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.",
"title": "Range"
}
},
{
"in": "query",
"name": "start_time",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
}
},
{
"in": "query",
"name": "end_time",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DashboardDataResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Dashboard not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Dashboard Data",
"tags": [
"Dashboards"
],
"x-tool": {
"description": "Answer a dashboard's query widgets (up to 24) for one window \u2014 the way to say what a dashboard shows, not just what it contains. Resolve the dashboard id with list_dashboards and match its name; never guess an id. Takes a window like run_widget_query (range preset or explicit bounds; neither means the site's default). Widgets come back in the dashboard's order with a status each: ok with rows (a series carries every bucket; any other display is capped at 25 rows, with truncated set), skipped for a trace feed (read those with list_traces and the feed's filters), or error with a reason. Every figure you report must come from these rows, and name the window it was answered for.",
"enabled": true,
"name": "get_dashboard_data"
}
}
},
"/api/v1/public/dataset-versions/{version_id}": {
"get": {
"description": "Read an immutable snapshot: the version plus its cases, whole or a page at a time.\n\nPaging is opt-in through `limit`, because the released SDKs pull a version with one\nrequest and never follow `next_cursor`; a default page would silently truncate them.\nA version's case set is unbounded in practice, so any other caller should page.\n`input`/`expected` come back as native JSON values.",
"operationId": "get_dataset_version",
"parameters": [
{
"in": "path",
"name": "version_id",
"required": true,
"schema": {
"title": "Version Id",
"type": "string"
}
},
{
"description": "Test cases per page. Omit it, with no cursor, to receive the whole version in one response, as an SDK pulling the snapshot it will run does; pass it to page.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"anyOf": [
{
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Test cases per page. Omit it, with no cursor, to receive the whole version in one response, as an SDK pulling the snapshot it will run does; pass it to page.",
"title": "Limit"
}
},
{
"description": "Opaque cursor from a previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor from a previous page",
"title": "Cursor"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDatasetVersionResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Read one dataset version and a page of its test cases",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "Read one immutable dataset version and its test cases (input, expected, metadata, and trace provenance where the case was captured from one). Always pass limit (for example 20) and follow next_cursor until it is null: without limit the whole version comes back in one response, which can be very large.",
"enabled": true,
"name": "get_dataset_version"
}
}
},
"/api/v1/public/datasets": {
"get": {
"description": "List datasets, newest first. `next_cursor` is null on the last page.",
"operationId": "list_datasets",
"parameters": [
{
"description": "Datasets per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Datasets per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor from a previous page",
"title": "Cursor"
}
},
{
"description": "Case-insensitive substring of the name",
"in": "query",
"name": "name",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring of the name",
"title": "Name"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDatasetsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List the project's evaluation datasets",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "List the project's evaluation datasets, newest first, with each dataset's current published version. Filter by a case-insensitive substring of the name. Use this for discovery before reading a specific dataset.",
"enabled": true,
"name": "list_datasets"
}
}
},
"/api/v1/public/datasets/{dataset_id}": {
"get": {
"description": "Read one dataset. `current_dataset_version_id` is null until a version is published.",
"operationId": "get_dataset",
"parameters": [
{
"in": "path",
"name": "dataset_id",
"required": true,
"schema": {
"title": "Dataset Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicDataset"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Read one evaluation dataset",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "Read one evaluation dataset by id: its name, description, key, and current published version. A dataset with no published version has none, and its cases cannot be read until one exists.",
"enabled": true,
"name": "get_dataset"
}
}
},
"/api/v1/public/datasets/{dataset_id}/versions": {
"get": {
"description": "List versions newest-first, each with its case count and whether it is current.",
"operationId": "list_dataset_versions",
"parameters": [
{
"in": "path",
"name": "dataset_id",
"required": true,
"schema": {
"title": "Dataset Id",
"type": "string"
}
},
{
"description": "Versions per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Versions per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor from a previous page",
"title": "Cursor"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDatasetVersionsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List a dataset's published versions",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "List a dataset's published versions, newest first, each with its case count and whether it is the current one. Versions are immutable snapshots: editing a dataset's test cases publishes a new version rather than changing an old one, while renaming a dataset or changing its description publishes nothing.",
"enabled": true,
"name": "list_dataset_versions"
}
}
},
"/api/v1/public/detectors": {
"get": {
"description": "List the detectors in the caller's project (newest first).",
"operationId": "list_detectors",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Only detectors created at or after this time (inclusive, ISO 8601)",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only detectors created at or after this time (inclusive, ISO 8601)",
"title": "Start After"
}
},
{
"description": "Only detectors created before this time (exclusive, ISO 8601)",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only detectors created before this time (exclusive, ISO 8601)",
"title": "End Before"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicDetectorListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to list detectors"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Detectors",
"tags": [
"Detectors"
],
"x-tool": {
"description": "List the project's detectors (id, name, template, enabled flag, creation time).",
"enabled": true,
"name": "list_detectors"
}
},
"post": {
"description": "Create a detector in a project the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Idempotent on the detector name within the project.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateDetectorRequest): The detector to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateDetectorResponse: The created (or matched) detector.",
"operationId": "create_detector",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDetectorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDetectorResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create a detector",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Create a detector (name, template, prompt, optional sampling/RCA settings) in a project \u2014 idempotent on the detector name within the project. The standard detector types (failure, hallucination, logic, task, safety) have canonical default instructions: pass the matching template id and OMIT prompt to use them. Only supply prompt when the user provides genuinely custom instructions \u2014 a supplied prompt is stored verbatim and overrides the template default.",
"enabled": true,
"name": "create_detector",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/detectors/findings": {
"get": {
"description": "List recent detector findings for the caller's project (newest first).",
"operationId": "list_findings",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Only findings at or after this time (inclusive, ISO 8601)",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only findings at or after this time (inclusive, ISO 8601)",
"title": "Start After"
}
},
{
"description": "Only findings before this time (exclusive, ISO 8601)",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only findings before this time (exclusive, ISO 8601)",
"title": "End Before"
}
},
{
"description": "Filter by detector id, name, or template",
"in": "query",
"name": "detector",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by detector id, name, or template",
"title": "Detector"
}
},
{
"description": "Filter to a single trace",
"in": "query",
"name": "trace_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter to a single trace",
"title": "Trace Id"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicFindingListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to list findings"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Findings",
"tags": [
"Detectors"
],
"x-tool": {
"description": "List detector findings for the project, optionally filtered by detector (id, name, or template), trace id, or time range.",
"enabled": true,
"name": "list_findings"
}
}
},
"/api/v1/public/detectors/findings/{finding_id}": {
"get": {
"description": "Get a single finding by id for the key's project.",
"operationId": "get_finding",
"parameters": [
{
"in": "path",
"name": "finding_id",
"required": true,
"schema": {
"title": "Finding Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FindingDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Finding not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to read finding"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Finding",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Fetch one detector finding by id, with its full analysis detail.",
"enabled": true,
"name": "get_finding"
}
}
},
"/api/v1/public/detectors/traces/{trace_id}/finding": {
"get": {
"description": "Get the finding for a single trace (findings are 1-per-trace).",
"operationId": "get_finding_by_trace",
"parameters": [
{
"in": "path",
"name": "trace_id",
"required": true,
"schema": {
"title": "Trace Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FindingDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Finding not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to read finding"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Finding By Trace",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Fetch the detector finding attached to a specific trace, if any.",
"enabled": true,
"name": "get_finding_by_trace"
}
}
},
"/api/v1/public/detectors/{detector_id}": {
"delete": {
"description": "Hard-delete a detector; its existing findings stay readable.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Not idempotent: a second delete of the same id is a 404.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n detector_id (str): The detector to delete.\n project_id (str): The project the detector belongs to.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteDetectorResponse: The removed detector.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "delete_detector",
"parameters": [
{
"in": "path",
"name": "detector_id",
"required": true,
"schema": {
"title": "Detector Id",
"type": "string"
}
},
{
"description": "The project the resource belongs to",
"in": "query",
"name": "project_id",
"required": true,
"schema": {
"description": "The project the resource belongs to",
"title": "Project Id",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteDetectorResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete a detector",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Permanently delete a detector; its existing findings stay readable. Requires a reason (3-500 characters) stating why \u2014 the user's actual instruction, recorded on the audit row. Resolve the id by listing the project's detectors and matching the name; never delete more than the user named.",
"enabled": true,
"name": "delete_detector",
"policy": {
"approvalClass": "approval",
"minRole": "MEMBER",
"tenancy": "project"
}
}
},
"get": {
"description": "Get one detector's full configuration for the key's project.",
"operationId": "get_detector",
"parameters": [
{
"in": "path",
"name": "detector_id",
"required": true,
"schema": {
"title": "Detector Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetectorDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Detector not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to read detector"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Detector",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Fetch one detector's full configuration by id: prompt, output schema, sample rate, RCA and detection settings, and trigger conditions.",
"enabled": true,
"name": "get_detector"
}
},
"patch": {
"description": "Edit a detector in a project the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Only the sent fields change; ``template`` is immutable.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n detector_id (str): The detector to edit.\n payload (UpdateDetectorRequest): The project and the fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateDetectorResponse: The updated detector and the changed fields.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "update_detector",
"parameters": [
{
"in": "path",
"name": "detector_id",
"required": true,
"schema": {
"title": "Detector Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDetectorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDetectorResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Name already in use"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Edit a detector",
"tags": [
"Detectors"
],
"x-tool": {
"description": "Edit a detector: name, prompt, enabled (the pause switch), sample_rate, enable_rca, output_schema, trigger_conditions, or the detection model settings. Send only the fields the user asked to change \u2014 fields left out are untouched, and a null detection_model/detection_provider/detection_source clears it. output_schema and trigger_conditions replace the whole array; [] removes the trigger. The template cannot change. Read the detector first so the proposal names its current values; the response lists the fields that actually changed.",
"enabled": true,
"name": "update_detector",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/evaluation-runs": {
"get": {
"description": "List evaluation runs, newest first, optionally one evaluation's or one status's.\n\nIdentity and status only: a run's counts and per-scorer means come from `read_run`, so\nlisting stays one query however many runs a page holds. `next_cursor` is null on the\nlast page.",
"operationId": "list_evaluation_runs",
"parameters": [
{
"description": "Runs per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Runs per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor from a previous page",
"title": "Cursor"
}
},
{
"description": "Only this evaluation's runs",
"in": "query",
"name": "evaluation_id",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Only this evaluation's runs",
"title": "Evaluation Id"
}
},
{
"description": "Only runs in this status",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"running",
"completed",
"completed_with_errors",
"failed",
"incomplete",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Only runs in this status",
"title": "Status"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListEvaluationRunsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List the project's evaluation runs",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "List evaluation runs, newest first. Filter by evaluation_id to see one evaluation's runs, or by status to see only runs in that state. Each row is identity and outcome only: which run it is, what was evaluated, the dataset version it pinned, its status, and when it started and finished. A run's counts and per-scorer means come from get_evaluation_run. Use this to find a run id.",
"enabled": true,
"name": "list_evaluation_runs"
}
},
"post": {
"description": "Register/start a run. Idempotent on ``client_run_id`` within an evaluation.",
"operationId": "register_run",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterRunRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterRunResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Request body too large"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Register an evaluation run",
"tags": [
"Offline Eval"
],
"x-mint": {
"content": "The TraceRoot SDKs call this endpoint for you; call it directly only where no SDK fits. It accepts a project API key only."
},
"x-tool": {
"enabled": false
}
}
},
"/api/v1/public/evaluation-runs/{run_id}": {
"get": {
"description": "Read a run's own summary: status, result counts, and per-score and per-metric\nmeans over the run's results.\n\nTyped rather than left to the catch-all so it appears in the published OpenAPI: an\nendpoint a CLI is expected to call must be in the contract the CLI generates from.\nSummary only, so the response is bounded by scorer count rather than case count.\n\nComparing two runs is not part of this read. It is a different question with its own\ntrust rules, and an optional parameter here would be too easily confused with the\nbaseline a run stores at registration.",
"operationId": "read_run",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"title": "Run Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReadRunResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project, or the run is outside the plan's retention window"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Read an evaluation run's summary",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "Read one evaluation run's summary: its status, result counts, per-scorer scores, and mean cost and duration per case. scored_count, task_error_count and scorer_error_count are null until the run completes. A case is errored or not_scored; passed and failed are older statuses, so passed_count and failed_count are usually 0. Each score and metric carries observed_count, the number of results it was taken over. A numeric score's value is its mean and a boolean score's is its pass rate. A categorical or mixed-type score, or one no result reported, has a null value: it has no mean, and is not a score of 0.",
"enabled": true,
"name": "get_evaluation_run"
}
}
},
"/api/v1/public/evaluation-runs/{run_id}/complete": {
"post": {
"description": "Complete/fail a run, reporting final completeness counts.",
"operationId": "complete_run",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"title": "Run Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteRunRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteRunResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Request body too large"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Complete/finalize an evaluation run",
"tags": [
"Offline Eval"
],
"x-mint": {
"content": "The TraceRoot SDKs call this endpoint for you; call it directly only where no SDK fits. It accepts a project API key only."
},
"x-tool": {
"enabled": false
}
}
},
"/api/v1/public/evaluation-runs/{run_id}/results": {
"post": {
"description": "Upsert one test-case result (and its scores). Idempotent on (run, test case).",
"operationId": "upsert_result",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"title": "Run Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpsertResultRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpsertResultResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Request body too large"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Upsert one test-case result with scores",
"tags": [
"Offline Eval"
],
"x-mint": {
"content": "The TraceRoot SDKs call this endpoint for you; call it directly only where no SDK fits. It accepts a project API key only."
},
"x-tool": {
"enabled": false
}
}
},
"/api/v1/public/evaluations": {
"get": {
"description": "List evaluations, newest first, each with its run count and latest run.\n\n`next_cursor` is null on the last page.",
"operationId": "list_evaluations",
"parameters": [
{
"description": "Evaluations per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Evaluations per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor from a previous page",
"title": "Cursor"
}
},
{
"description": "Case-insensitive substring of the name",
"in": "query",
"name": "name",
"required": false,
"schema": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring of the name",
"title": "Name"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListEvaluationsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No access to this project"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List the project's evaluations",
"tags": [
"Offline Eval"
],
"x-tool": {
"description": "List the project's evaluations, newest first: each one's name, the key an SDK reports it under, the dataset it runs against, how many runs it has, and its latest run. Filter by a case-insensitive substring of the name. An evaluation that has never been run reports a null latest_run. Use this to find an evaluation before listing its runs.",
"enabled": true,
"name": "list_evaluations"
}
}
},
"/api/v1/public/projects": {
"get": {
"description": "List the projects the authenticated user can access, across workspaces.\n\nA user-credential-only discovery op (no ``project_id``). Projects are\nflattened across the user's workspaces and tagged with their owning\nworkspace; the answer is what you pass as ``project_id`` to a project-scoped\nrequest.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or CLI\n access JWT); carries the resolved ``user_id`` and stamps the per-user\n rate-limit identity.\n workspace_id (str | None): Optional filter; when given, only projects in\n that workspace are returned.\n\nReturns:\n PublicProjectListResponse: The accessible projects (id, name,\n workspace_id, workspace_name, workspace_is_demo).",
"operationId": "list_projects",
"parameters": [
{
"description": "Restrict the result to projects in this workspace.",
"in": "query",
"name": "workspace_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Restrict the result to projects in this workspace.",
"title": "Workspace Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicProjectListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Projects",
"tags": [
"Account"
],
"x-tool": {
"description": "List the projects the logged-in user can access, across workspaces (id, name, workspace). User-credential-only account discovery: use it to resolve the project_id a project-scoped request needs. Optionally filter by workspace_id.",
"enabled": true,
"name": "list_projects"
}
},
"post": {
"description": "Create a project in a workspace the authenticated user can write to.\n\nRequires MEMBER role or higher in the workspace (the write service decides).\nIdempotent on the project name within the workspace.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateProjectRequest): The project to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateProjectResponse: The created (or matched) project.",
"operationId": "create_project",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create a project",
"tags": [
"Account"
],
"x-tool": {
"agentHiddenParams": [
"trace_ttl_days"
],
"description": "Create a project in a workspace the logged-in user can write to (idempotent on the project name within the workspace).",
"enabled": true,
"name": "create_project",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "workspace"
}
}
}
},
"/api/v1/public/projects/{project_id}": {
"delete": {
"description": "Soft-delete a project.\n\nRequires ADMIN role in the project's workspace (the write service\ndecides). The project drops out of every list and read and its access\nkeys stop authenticating; its data stays for the retention window.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n project_id (str): The project to delete.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteProjectResponse: The removed project.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "delete_project",
"parameters": [
{
"in": "path",
"name": "project_id",
"required": true,
"schema": {
"title": "Project Id",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteProjectResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete a project",
"tags": [
"Account"
],
"x-tool": {
"description": "Delete a project: it drops out of every list and read and its API keys stop authenticating (its data stays for the retention window). Requires ADMIN in the workspace and a reason (3-500 characters) that is recorded on the audit row.",
"enabled": true,
"name": "delete_project",
"policy": {
"approvalClass": "approval",
"minRole": "ADMIN",
"tenancy": "workspace"
}
}
},
"patch": {
"description": "Edit a project's name or trace retention.\n\nRequires ADMIN role in the project's workspace (the write service\ndecides). A null ``trace_ttl_days`` returns retention to the plan default.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n project_id (str): The project to edit.\n payload (UpdateProjectRequest): The fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateProjectResponse: The updated project and the changed fields.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "update_project",
"parameters": [
{
"in": "path",
"name": "project_id",
"required": true,
"schema": {
"title": "Project Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProjectRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProjectResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Name already in use"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Edit a project",
"tags": [
"Account"
],
"x-tool": {
"agentHiddenParams": [
"trace_ttl_days"
],
"description": "Edit a project's name (or, via the API, its trace retention). Fields left out are untouched; a null trace_ttl_days returns retention to the plan default. Requires ADMIN in the workspace. The response lists the fields that actually changed.",
"enabled": true,
"name": "update_project",
"policy": {
"approvalClass": "confirm",
"minRole": "ADMIN",
"tenancy": "workspace"
}
}
}
},
"/api/v1/public/sessions": {
"get": {
"description": "List unique sessions for the caller's project with trace counts.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context (API key or user\n session token); scopes the read to its project and stamps the\n rate-limit identity.\n limit (int): Items per page (1-200).\n search_query (str | None): Substring match on session id.\n start_after (datetime | None): Inclusive lower bound on trace time.\n end_before (datetime | None): Exclusive upper bound on trace time.\n\nReturns:\n SessionListResponse: Session summaries, newest first.\n\nRaises:\n HTTPException: 500 on a reader failure.",
"operationId": "list_sessions",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Search by session_id",
"in": "query",
"name": "search_query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Search by session_id",
"title": "Search Query"
}
},
{
"description": "Only sessions with traces at or after this time (inclusive, ISO 8601)",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only sessions with traces at or after this time (inclusive, ISO 8601)",
"title": "Start After"
}
},
{
"description": "Only sessions with traces before this time (exclusive, ISO 8601)",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only sessions with traces before this time (exclusive, ISO 8601)",
"title": "End Before"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to list sessions"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Sessions",
"tags": [
"Sessions"
],
"x-tool": {
"description": "List recent sessions (groups of traces sharing a session id) for the project, with trace counts and durations. Search by session id substring.",
"enabled": true,
"name": "list_sessions"
}
}
},
"/api/v1/public/sessions/{session_id}": {
"get": {
"description": "Get one session with all its traces for the key's project.\n\nRetention uses the silent list-style clamp rather than a 403: a session\nthat contains traces older than the plan window degrades to showing only\nthe in-window traces instead of failing outright.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context (API key or user\n session token); scopes the read to its project and stamps the\n rate-limit identity.\n session_id (str): Session to fetch.\n start_after (datetime | None): Inclusive lower bound on trace time.\n end_before (datetime | None): Exclusive upper bound on trace time.\n\nReturns:\n SessionDetailResponse: The session overview and its traces.\n\nRaises:\n HTTPException: 404 if the session is missing or outside the key's\n project, 500 on a reader failure.",
"operationId": "get_session",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
},
{
"description": "Only traces at or after this time (inclusive, ISO 8601)",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only traces at or after this time (inclusive, ISO 8601)",
"title": "Start After"
}
},
{
"description": "Only traces before this time (exclusive, ISO 8601)",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only traces before this time (exclusive, ISO 8601)",
"title": "End Before"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionDetailResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Session not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to get session"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Session",
"tags": [
"Sessions"
],
"x-tool": {
"description": "Fetch one session with all its traces (ids, names, status, I/O summaries). Use before deep-diving individual traces of a conversation.",
"enabled": true,
"name": "get_session"
}
}
},
"/api/v1/public/signals": {
"get": {
"description": "List the signals in the caller's project (newest first). Merged signals are left out.",
"operationId": "list_signals",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "0-based page index",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 0,
"description": "0-based page index",
"maximum": 10000,
"minimum": 0,
"title": "Page",
"type": "integer"
}
},
{
"description": "Only signals with this status",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"open",
"resolved",
"dismissed"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Only signals with this status",
"title": "Status"
}
},
{
"description": "Only signals of this detector",
"in": "query",
"name": "detector_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Only signals of this detector",
"title": "Detector Id"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSignalListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Signals",
"tags": [
"Signals"
],
"x-tool": {
"description": "List the project's signals, newest first: the recurring problems that detector findings are grouped into, with status (open, resolved, dismissed), detector, hit count, reopen count and the state of the current root cause analysis. Filter by status or detector_id. Merged signals are left out. Returns 50 results by default; increment page to fetch subsequent pages until all needed signals are found.",
"enabled": true,
"name": "list_signals"
}
}
},
"/api/v1/public/signals/{signal_id}": {
"get": {
"description": "Get one signal of the caller's project. A merged signal names the signal it moved to.",
"operationId": "get_signal",
"parameters": [
{
"in": "path",
"name": "signal_id",
"required": true,
"schema": {
"title": "Signal Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignalDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Signal not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Signal",
"tags": [
"Signals"
],
"x-tool": {
"description": "Fetch one signal by id, including when it was resolved. A merged signal names the signal its findings moved to in merged_into_id. Resolve the signal id by listing signals \u2014 never guess an id.",
"enabled": true,
"name": "get_signal"
}
}
},
"/api/v1/public/signals/{signal_id}/status": {
"patch": {
"description": "Resolve or reopen a signal. Dismissing is not possible here.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Resolving needs a ``reason``; the reason ``other`` also\nneeds a ``note``. A resolved signal opens again by itself when its\ndetector finds the problem in a trace that started after the resolve. Send\n``expected_status`` to refuse the change when someone else changed the\nstatus first. Setting the status the signal already has changes nothing.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n signal_id (str): The signal to change.\n payload (SignalStatusRequest): The project, the target status, and\n the reason, note and expected status.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n SignalStatusResponse: The signal with its new status.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "set_signal_status",
"parameters": [
{
"in": "path",
"name": "signal_id",
"required": true,
"schema": {
"title": "Signal Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignalStatusRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignalStatusResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The status changed since the caller read it, or the signal was merged"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Resolve or reopen a signal",
"tags": [
"Signals"
],
"x-tool": {
"description": "Resolve or reopen a signal. Resolving needs a reason (fixed_elsewhere, fixed_by_pr, already_fixed_before, other); 'other' also needs a note. A resolved signal opens again by itself when its detector finds the problem in a trace that started after the resolve. Dismissing is not possible here: a dismissed signal never reopens, so a person dismisses in the web app. Send expected_status to refuse the change when the status changed since you read it (a conflict). Setting the current status changes nothing.",
"enabled": true,
"name": "set_signal_status",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/sql": {
"post": {
"description": "Run one read-only SQL query scoped to the caller's project.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context. Its ``project_id``\n is the only project this query can ever see.\n body (SqlRequest): The query, optional parameter values, and an optional\n row cap that the service clamps down to the server ceiling.\n\nReturns:\n SqlResponse: Columns, rows, and whether more rows matched than were\n returned.\n\nRaises:\n HTTPException: 400 when the query breaks the read-only contract or asks\n for more than the server allows, 429 when no query slot is free,\n 500 when execution fails for a reason the caller cannot act on.",
"operationId": "run_sql",
"parameters": [
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SqlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SqlResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The query breaks the read-only contract, asked for more than the server allows, or the credential names no project"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The credential cannot access this project"
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Request body too large"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded, or too many queries are already running"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Query execution failed"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Run Sql",
"tags": [
"SQL"
],
"x-tool": {
"description": "Run one read-only SQL query over the project's own spans and traces and return the rows. Use get_sql_schema first to see the columns available; the query may only read the curated spans and traces tables, and results are capped and may be truncated.",
"enabled": true,
"name": "run_sql",
"policy": {
"approvalClass": "none",
"minRole": "VIEWER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/sql/schema": {
"get": {
"description": "Return the curated tables and columns available to public SQL.\n\nRead from the same contract the validator and the rewriter derive from, so\nwhat this advertises and what a query may reference cannot drift apart.",
"operationId": "get_sql_schema",
"parameters": [
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SqlSchemaResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The credential names no project"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The credential cannot access this project"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Validation error"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rate limit exceeded"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Sql Schema",
"tags": [
"SQL"
],
"x-tool": {
"description": "List the tables and columns available to run_sql, with their types. Read this before writing a query: it is the whole surface a query may reference.",
"enabled": true,
"name": "get_sql_schema"
}
}
},
"/api/v1/public/traces": {
"get": {
"description": "List recent traces for the caller's project (newest first).\n\nOffline-evaluation traces are excluded by default; pass\n``include_evaluations=true`` to include them.",
"operationId": "list_traces",
"parameters": [
{
"description": "Items per page",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Only traces that started at or after this time (inclusive, ISO 8601)",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only traces that started at or after this time (inclusive, ISO 8601)",
"title": "Start After"
}
},
{
"description": "Only traces that started before this time (exclusive, ISO 8601)",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only traces that started before this time (exclusive, ISO 8601)",
"title": "End Before"
}
},
{
"description": "Include traces produced by offline-evaluation runs. Excluded by default so evaluation runs do not appear in the production trace list.",
"in": "query",
"name": "include_evaluations",
"required": false,
"schema": {
"default": false,
"description": "Include traces produced by offline-evaluation runs. Excluded by default so evaluation runs do not appear in the production trace list.",
"title": "Include Evaluations",
"type": "boolean"
}
},
{
"description": "Filter by trace name (substring match)",
"in": "query",
"name": "name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by trace name (substring match)",
"title": "Name"
}
},
{
"description": "Filter by the user id recorded on the trace",
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by the user id recorded on the trace",
"title": "User Id"
}
},
{
"description": "Search across trace_id, name, session_id, user_id",
"in": "query",
"name": "search_query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Search across trace_id, name, session_id, user_id",
"title": "Search Query"
}
},
{
"content": {
"application/json": {
"schema": {
"items": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"field": {
"const": "trace_id",
"title": "Trace ID",
"type": "string"
},
"op": {
"enum": [
"eq",
"contains"
],
"type": "string"
},
"value": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "signal_id",
"title": "Signal ID",
"type": "string"
},
"op": {
"enum": [
"eq"
],
"type": "string"
},
"value": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "model_name",
"title": "Model",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "environment",
"title": "Environment",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "span_kind",
"title": "Span kind",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "status",
"title": "Status",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "error_type",
"title": "Error type",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "name",
"title": "Span name",
"type": "string"
},
"op": {
"enum": [
"in"
],
"type": "string"
},
"value": {
"items": {
"maxLength": 1024,
"type": "string"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "cost",
"title": "Cost",
"type": "string"
},
"op": {
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte"
],
"type": "string"
},
"value": {
"maximum": 999999999,
"minimum": 0,
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "total_tokens",
"title": "Tokens",
"type": "string"
},
"op": {
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte"
],
"type": "string"
},
"value": {
"maximum": 9223372036854775807,
"minimum": 0,
"type": "integer"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "duration_ms",
"title": "Latency",
"type": "string"
},
"op": {
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte"
],
"type": "string"
},
"value": {
"maximum": 9223372036854775807,
"minimum": 0,
"type": "integer"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "errors",
"title": "Errors",
"type": "string"
},
"op": {
"enum": [
"eq",
"gt",
"gte",
"lt",
"lte"
],
"type": "string"
},
"value": {
"maximum": 18446744073709551615,
"minimum": 0,
"type": "integer"
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"field": {
"const": "metadata",
"title": "Metadata",
"type": "string"
},
"key": {
"description": "Which metadata key the value is compared against",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"op": {
"enum": [
"eq",
"contains"
],
"type": "string"
},
"value": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
}
},
"required": [
"field",
"key",
"op",
"value"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
}
}
},
"description": "JSON array of typed filter predicates ({field, op, value}); the field catalog and per-field operators are defined in the schema",
"in": "query",
"name": "filters",
"required": false
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicTraceListResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid filters parameter"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to list traces"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Traces",
"tags": [
"Traces"
],
"x-tool": {
"description": "List recent traces for the project (newest first). Filter by time range, trace name, user id, or a free-text search across trace/session/user ids and names. Use this for discovery before fetching a specific trace. Structured filters (model, environment, cost, tokens, latency, error count, keyed metadata) are available via the typed filters parameter.",
"enabled": true,
"name": "list_traces"
}
},
"post": {
"description": "Ingest OTLP trace data.\n\nAccepts OTLP protobuf format only (optionally gzip compressed).\nProtobuf is converted to camelCase JSON before storage in S3.\n\nS3 path: events/otel/{project_id}/{yyyy}/{mm}/{dd}/{hh}/{uuid}.json\n\nHeaders:\n Authorization: Bearer \n Content-Encoding: gzip (optional)\n Content-Type: application/x-protobuf\n\nBody:\n OTLP trace data in protobuf format",
"operationId": "ingest_traces",
"requestBody": {
"content": {
"application/x-protobuf": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IngestResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request body"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"402": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Free plan limit exceeded"
},
"415": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unsupported media type"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Storage error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Ingest Traces",
"tags": [
"Traces"
],
"x-mint": {
"content": "The TraceRoot SDKs call this endpoint for you; call it directly only where no SDK fits. It accepts a project API key only.\n\nSend the body as OTLP protobuf with `Content-Type: application/x-protobuf`, optionally gzip-compressed with `Content-Encoding: gzip`."
},
"x-tool": {
"enabled": false
}
}
},
"/api/v1/public/traces/filter-values/{field}": {
"get": {
"description": "Distinct values for an open-ended categorical filter field.\n\nThe values-discovery companion to the typed ``filters`` parameter on the\ntrace list: the filterable field catalog lives in the generated schema,\nwhile a field's current values are dynamic per project. Only fields the\nregistry marks as distinct-query (model_name, environment) are listable;\nthe field is resolved through the registry before it reaches SQL, so it can\nnever be a raw client-supplied column name.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context (API key or user\n session token); scopes the read to its project and stamps the\n rate-limit identity.\n field (str): The categorical field to enumerate.\n start_after (datetime | None): Lower bound on span start time (active\n window).\n end_before (datetime | None): Upper bound on span start time (active\n window), symmetric with ``start_after`` so options match the list's\n window.\n\nReturns:\n FilterValuesResponse: Distinct values ordered by descending frequency.\n\nRaises:\n HTTPException: 400 if the field is unknown or not a distinct-query\n categorical, 500 on a reader failure.",
"operationId": "list_trace_filter_values",
"parameters": [
{
"in": "path",
"name": "field",
"required": true,
"schema": {
"title": "Field",
"type": "string"
}
},
{
"description": "Only consider spans starting at or after this timestamp",
"in": "query",
"name": "start_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only consider spans starting at or after this timestamp",
"title": "Start After"
}
},
{
"description": "Only consider spans starting before this timestamp",
"in": "query",
"name": "end_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Only consider spans starting before this timestamp",
"title": "End Before"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FilterValuesResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Field is not filterable by distinct values"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to list filter values"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Trace Filter Values",
"tags": [
"Traces"
],
"x-tool": {
"description": "Discover the current values of a categorical trace filter field (e.g. model_name, environment) for the project \u2014 use before filtering the trace list by that field.",
"enabled": true,
"name": "list_trace_filter_values"
}
}
},
"/api/v1/public/traces/{trace_id}": {
"get": {
"description": "Get a single trace for the caller's project.\n\nDefaults to the lightweight `skeleton` projection (no per-span I/O); pass\n`fields=full` (or `fields=io,metadata`) for per-span input/output/metadata.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context (API key or user\n session token); scopes the read to its project and stamps the\n rate-limit identity.\n trace_id (str): Trace to fetch.\n fields (str | None): Comma-separated projection groups (e.g. ``io``,\n ``metadata``) or an alias (``skeleton``/``full``). ``None`` selects\n the default `skeleton` projection.\n\nReturns:\n PublicTraceDetailResponse: The trace with span skeletons, plus per-span\n I/O when the projection requests it.\n\nRaises:\n HTTPException: 400 if `fields` is invalid, 404 if the trace is missing\n or outside the key's project, 500 on a reader failure.",
"operationId": "get_trace",
"parameters": [
{
"in": "path",
"name": "trace_id",
"required": true,
"schema": {
"title": "Trace Id",
"type": "string"
}
},
{
"description": "Comma-separated field groups to include: 'core' (tree/timing/status, always included), 'usage' (tokens/cost), 'io' (per-span input/output), 'metadata' (per-span metadata). Aliases: 'skeleton' (core,usage), 'full' (everything). Unknown groups return 400.",
"in": "query",
"name": "fields",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Comma-separated field groups to include: 'core' (tree/timing/status, always included), 'usage' (tokens/cost), 'io' (per-span input/output), 'metadata' (per-span metadata). Aliases: 'skeleton' (core,usage), 'full' (everything). Unknown groups return 400.",
"title": "Fields"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicTraceDetailResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid fields parameter"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Trace not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to get trace"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Trace",
"tags": [
"Traces"
],
"x-tool": {
"description": "Fetch one trace with its span tree. Defaults to the lightweight skeleton projection; pass fields=full for per-span input/output/metadata.",
"enabled": true,
"name": "get_trace"
}
}
},
"/api/v1/public/traces/{trace_id}/export": {
"get": {
"description": "Export the V1 bundle (trace + spans + git_context + manifest) for the caller's project.\n\nDefaults to the `full` projection \u2014 an export is explicit intent to take the\ncomplete trace, so per-span input/output/metadata are included unless the\ncaller narrows `fields`. `bundle.trace` equals the `traces get` payload at the\nsame projection.\n\nRate limited on its own `export` bucket because it builds and serializes the\nfull bundle.\n\nArgs:\n auth (DualStampedAuth): Resolved credential context (API key or user\n session token); scopes the read to its project and stamps the\n rate-limit identity.\n trace_id (str): Trace to export.\n fields (str | None): Comma-separated projection groups or an alias\n (``skeleton``/``full``). ``None`` selects the default `full`\n projection.\n\nReturns:\n PublicTraceExportResponse: The V1 export bundle (manifest, trace, spans,\n git_context) at the requested projection.\n\nRaises:\n HTTPException: 400 if `fields` is invalid, 404 if the trace is missing\n or outside the key's project, 500 on a reader failure.",
"operationId": "export_trace",
"parameters": [
{
"in": "path",
"name": "trace_id",
"required": true,
"schema": {
"title": "Trace Id",
"type": "string"
}
},
{
"description": "Comma-separated field groups to include: 'core' (tree/timing/status, always included), 'usage' (tokens/cost), 'io' (per-span input/output), 'metadata' (per-span metadata). Aliases: 'skeleton' (core,usage), 'full' (everything). Unknown groups return 400.",
"in": "query",
"name": "fields",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Comma-separated field groups to include: 'core' (tree/timing/status, always included), 'usage' (tokens/cost), 'io' (per-span input/output), 'metadata' (per-span metadata). Aliases: 'skeleton' (core,usage), 'full' (everything). Unknown groups return 400.",
"title": "Fields"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicTraceExportResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid fields parameter"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Trace not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Failed to get trace"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Export Trace",
"tags": [
"Traces"
],
"x-tool": {
"description": "Export the complete bundle (trace, spans, git context, manifest) for one trace.",
"enabled": true,
"name": "export_trace"
}
}
},
"/api/v1/public/whoami": {
"get": {
"description": "Return the identity the authenticated API key maps to.",
"operationId": "whoami",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhoamiResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Whoami",
"tags": [
"Whoami"
],
"x-tool": {
"description": "Identify the project and workspace the current credential belongs to.",
"enabled": true,
"name": "whoami"
}
}
},
"/api/v1/public/widgets": {
"post": {
"description": "Create a widget on a dashboard the authenticated user can write to.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). Strict create \u2014 never idempotent, ``created`` is always\n``true`` on success.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateWidgetRequest): The widget to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateWidgetResponse: The created widget.",
"operationId": "create_widget",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWidgetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWidgetResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create a dashboard widget",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Add a widget (title, type, spec) to an existing dashboard. Type \"query\" charts a metric (spec: view/filters/metric/breakdown/display); type \"trace_feed\" lists recent traces (spec: predicate filters + limit). Strict create: every call adds a new widget. The spec schema enumerates the only available views, metrics, filter operators, and display types \u2014 nothing outside it exists. If the user asks for a visualization or option that is not in the schema (for example a display type the enum lacks), say so explicitly and propose the closest available match instead of silently substituting. Pick the view first \u2014 spans and traces expose different fields, and the enums in this schema are the complete field vocabulary for each view. If the user asks for a dimension or metric that exists on neither view, say so and propose the closest available one (for example \"traces by model\" is built on the spans view via model_name).",
"enabled": true,
"name": "create_widget",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/widgets/query": {
"post": {
"description": "Run a widget spec for a window and return its rows with the window answered.",
"operationId": "run_widget_query",
"parameters": [
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WidgetQueryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WidgetQueryResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Run Widget Query",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Run a widget query and return its rows \u2014 the way to answer a metric question (error counts, p95 latency, cost by model) without a dashboard existing. Takes the same spec shape as create_widget (view, metric, breakdown, display, filters) plus a window: a range preset by the site picker's id (1h, 1d, 7d, 30d, \u2026) or explicit start_time/end_time; neither means the site's default 24-hour window. The response echoes the window it was answered for and says when retention clamped it. A read that happens to be a POST: nothing is written.",
"enabled": true,
"name": "run_widget_query",
"policy": {
"approvalClass": "none",
"minRole": "VIEWER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/widgets/{widget_id}": {
"delete": {
"description": "Hard-delete a widget and its entry in the dashboard's layout.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides).\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n widget_id (str): The widget to delete.\n project_id (str): The project the widget's dashboard belongs to.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteWidgetResponse: The removed widget.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "delete_widget",
"parameters": [
{
"in": "path",
"name": "widget_id",
"required": true,
"schema": {
"title": "Widget Id",
"type": "string"
}
},
{
"description": "The project the resource belongs to",
"in": "query",
"name": "project_id",
"required": true,
"schema": {
"description": "The project the resource belongs to",
"title": "Project Id",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWidgetResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete a dashboard widget",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Permanently delete one widget from its dashboard (its layout slot is removed with it). Requires a reason (3-500 characters) stating why \u2014 the user's actual instruction, recorded on the audit row. Resolve the id from the dashboard's detail; never delete more than the user named.",
"enabled": true,
"name": "delete_widget",
"policy": {
"approvalClass": "approval",
"minRole": "MEMBER",
"tenancy": "project"
}
}
},
"get": {
"description": "Get one saved widget's definition, with its dashboard, for the caller's project.",
"operationId": "get_widget",
"parameters": [
{
"in": "path",
"name": "widget_id",
"required": true,
"schema": {
"title": "Widget Id",
"type": "string"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WidgetDetail"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Widget not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Widget",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Fetch one saved widget's definition by id: its title, type, the query spec exactly as stored (what get_widget_data runs), display config, timestamps, and the id and name of the dashboard it sits on. Resolve a widget id from get_dashboard (which lists a dashboard's widgets) \u2014 never guess an id. For what the widget shows, use get_widget_data.",
"enabled": true,
"name": "get_widget"
}
},
"patch": {
"description": "Edit a widget's title, spec, or display config.\n\nRequires MEMBER role or higher in the project's workspace (the write\nservice decides). A sent ``spec`` replaces the whole spec and is checked\nagainst the widget's stored type by the service; ``type`` is immutable.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n widget_id (str): The widget to edit.\n payload (UpdateWidgetRequest): The project and the fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateWidgetResponse: The updated widget and the changed fields.\n\nRaises:\n HTTPException: The write service's 400/403/404 verbatim, or a 503\n when its response is ambiguous.",
"operationId": "update_widget",
"parameters": [
{
"in": "path",
"name": "widget_id",
"required": true,
"schema": {
"title": "Widget Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWidgetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWidgetResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Edit a dashboard widget",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Edit a widget's title, spec, or display_config. Fields left out are untouched; a sent spec replaces the whole spec and must be in the dialect of the widget's existing type (query: view/filters/metric/breakdown/display; trace_feed: predicate filters + limit) \u2014 the type itself cannot change. A null display_config resets it. Read the widget's dashboard first so the new spec starts from the current one; the spec schema enumerates the only available views, metrics, filter operators, and display types. The response lists the fields that actually changed.",
"enabled": true,
"name": "update_widget",
"policy": {
"approvalClass": "confirm",
"minRole": "MEMBER",
"tenancy": "project"
}
}
}
},
"/api/v1/public/widgets/{widget_id}/data": {
"get": {
"description": "Answer one saved widget for a window, with a status instead of an exception.",
"operationId": "get_widget_data",
"parameters": [
{
"in": "path",
"name": "widget_id",
"required": true,
"schema": {
"title": "Widget Id",
"type": "string"
}
},
{
"description": "A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.",
"in": "query",
"name": "range",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"30m",
"1h",
"3h",
"6h",
"1d",
"7d",
"14d",
"30d",
"60d",
"90d"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.",
"title": "Range"
}
},
{
"in": "query",
"name": "start_time",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
}
},
{
"in": "query",
"name": "end_time",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
}
},
{
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.",
"title": "Project Id"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WidgetDataResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Widget not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Get Widget Data",
"tags": [
"Widgets"
],
"x-tool": {
"description": "Answer one saved widget for a window \u2014 the way to say what a widget shows without re-sending its spec. Prefer this over run_widget_query whenever the widget already exists on a dashboard; run_widget_query is for a spec that is saved nowhere. Takes a widget id plus a window like run_widget_query (range preset or explicit start_time/end_time; neither means the site's default). The answer carries a status: ok with every row the engine returns (a series comes back whole; no row cap), skipped for a trace feed or legacy detector widget (read those with list_traces and the feed's filters), or error with a reason when the stored spec no longer runs. Every figure you report must come from these rows, and name the window it was answered for \u2014 the response echoes it and says when retention clamped it.",
"enabled": true,
"name": "get_widget_data"
}
}
},
"/api/v1/public/workspaces": {
"get": {
"description": "List the workspaces the authenticated user belongs to.\n\nA user-credential-only discovery op (no ``project_id``). Use it, then\n``list_projects``, to resolve the project a subsequent request scopes to.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or CLI\n access JWT); carries the resolved ``user_id`` and stamps the per-user\n rate-limit identity.\n\nReturns:\n PublicWorkspaceListResponse: The user's workspaces (id, name, role,\n is_demo); the public demo workspace, when present, comes last.",
"operationId": "list_workspaces",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicWorkspaceListResponse"
}
}
},
"description": "Successful Response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "List Workspaces",
"tags": [
"Account"
],
"x-tool": {
"description": "List the workspaces the logged-in user belongs to (id, name, role). User-credential-only account discovery: it needs no project_id and is not available to project-scoped API keys.",
"enabled": true,
"name": "list_workspaces"
}
},
"post": {
"description": "Create a workspace administered by the authenticated user.\n\nIdempotent: re-creating a workspace the user already administers under the\nsame name returns that workspace with ``created: false``.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n payload (CreateWorkspaceRequest): The workspace to create.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n CreateWorkspaceResponse: The created (or matched) workspace.",
"operationId": "create_workspace",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkspaceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Name already used by a workspace the user no longer administers"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Create a workspace",
"tags": [
"Account"
],
"x-tool": {
"description": "Create a workspace administered by the logged-in user. Idempotent: re-creating a same-named workspace the caller already administers returns it instead of duplicating.",
"enabled": true,
"name": "create_workspace",
"policy": {
"approvalClass": "confirm",
"minRole": "VIEWER",
"tenancy": "account"
}
}
}
},
"/api/v1/public/workspaces/{workspace_id}": {
"delete": {
"description": "Hard-delete a workspace and everything in it.\n\nRequires ADMIN role in the workspace (the write service decides); a\nworkspace outside the caller's memberships is a 403, as on the update.\nThe cascade removes every project, its data references, access keys,\nmemberships and invites; the typed ``name`` must equal the workspace's\ncurrent name, and the caller's only workspace cannot be deleted.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n workspace_id (str): The workspace to delete.\n name (str): The workspace's current name, as a typed confirmation.\n reason (str): Why it is being deleted; recorded on the audit row.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n DeleteWorkspaceResponse: The removed workspace and the cascade counts.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "delete_workspace",
"parameters": [
{
"in": "path",
"name": "workspace_id",
"required": true,
"schema": {
"title": "Workspace Id",
"type": "string"
}
},
{
"description": "The workspace's current name, typed as confirmation",
"in": "query",
"name": "name",
"required": true,
"schema": {
"description": "The workspace's current name, typed as confirmation",
"title": "Name",
"type": "string"
}
},
{
"description": "Why the resource is being deleted; recorded on the audit row",
"in": "query",
"name": "reason",
"required": true,
"schema": {
"description": "Why the resource is being deleted; recorded on the audit row",
"maxLength": 500,
"minLength": 3,
"title": "Reason",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The typed name does not match, or this is the caller's only workspace"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Delete a workspace",
"tags": [
"Account"
],
"x-tool": {
"description": "Permanently delete a workspace and everything in it: every project, its access keys, memberships and invites. Requires ADMIN, the workspace's current name typed as confirmation, and a reason (3-500 characters) that is recorded on the audit row. The caller's only workspace cannot be deleted. Not reversible.",
"enabled": true,
"name": "delete_workspace",
"policy": {
"approvalClass": "approval",
"minRole": "ADMIN",
"tenancy": "account"
}
}
},
"patch": {
"description": "Rename a workspace the authenticated user administers.\n\nRequires ADMIN role in the workspace (the write service decides).\nWorkspace membership is the tenancy here, so a workspace outside the\ncaller's memberships is a 403 rather than a 404, as on the project\ncreate; a name the caller already administers a workspace under is a\n409.\n\nArgs:\n request (Request): Incoming request (rate-limit plumbing).\n response (Response): Outgoing response (rate-limit plumbing).\n auth (AccountStampedAuth): Account-scope user auth (session token or\n CLI access JWT); its resolved ``user_id`` becomes the actor.\n workspace_id (str): The workspace to edit.\n payload (UpdateWorkspaceRequest): The fields to change.\n _live (None): Write-path liveness gate (blocks a revoked JWT session).\n\nReturns:\n UpdateWorkspaceResponse: The updated workspace and the changed fields.\n\nRaises:\n HTTPException: The write service's 400/403/404/409 verbatim, or a\n 503 when its response is ambiguous.",
"operationId": "update_workspace",
"parameters": [
{
"in": "path",
"name": "workspace_id",
"required": true,
"schema": {
"title": "Workspace Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkspaceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Invalid request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Authentication failed or session revoked"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Insufficient role or wrong credential kind"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Name already in use"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Write service unavailable"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "Rename a workspace",
"tags": [
"Account"
],
"x-tool": {
"description": "Rename a workspace the logged-in user administers. Fields left out are untouched. The response lists the fields that actually changed; a name the caller already uses for another workspace is a conflict.",
"enabled": true,
"name": "update_workspace",
"policy": {
"approvalClass": "confirm",
"minRole": "ADMIN",
"tenancy": "account"
}
}
}
}
},
"servers": [
{
"description": "TraceRoot Cloud",
"url": "https://app.traceroot.ai"
},
{
"description": "Self-hosted",
"url": "{baseUrl}",
"variables": {
"baseUrl": {
"default": "http://localhost:8000",
"description": "Your TraceRoot backend URL"
}
}
}
]
}