{ "openapi": "3.1.0", "info": { "title": "DecimalAI Platform", "description": "Agent Dataset Lifecycle Platform — Backend API", "version": "0.1.0" }, "paths": { "/api/v1/agents": { "get": { "tags": [ "agents" ], "summary": "List agents", "description": "List distinct agents with summary stats.\n\nReturns each agent's name, trace count, latest manifest info,\nand unreviewed trace count. Also discovers sub-agents from\nLlmCall.agent_name that don't have their own top-level traces.\n\nResults are workspace-scoped: filters by workspace_id when available,\nwith fallback for pre-workspace data (workspace_id IS NULL).", "operationId": "list_agents_api_v1_agents_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "H1088: optional cap on returned agents. Default (None) returns the full list — preserves backward compat. Max 1000.", "title": "Limit" }, "description": "H1088: optional cap on returned agents. Default (None) returns the full list — preserves backward compat. Max 1000." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "H1088: optional offset for pagination. Ignored when limit is None.", "default": 0, "title": "Offset" }, "description": "H1088: optional offset for pagination. Ignored when limit is None." }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "H1346 (improve#887): when False (default), hide agents whose agent_name starts with `__` — the convention for internal test fixtures (soak SDK runs produce `__soak_sdk_basic_` agents that otherwise dominate a real user's dashboard). Set True for debugging or admin tooling that needs to see the full set.", "default": false, "title": "Include Fixtures" }, "description": "H1346 (improve#887): when False (default), hide agents whose agent_name starts with `__` — the convention for internal test fixtures (soak SDK runs produce `__soak_sdk_basic_` agents that otherwise dominate a real user's dashboard). Set True for debugging or admin tooling that needs to see the full set." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "agents": [ { "agent_name": "travel-planner", "trace_count": 1250, "is_subagent": false, "latest_manifest": { "id": "mfst_001", "version_label": "v2.1" }, "unreviewed_count": 42 } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/agents\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nfor agent in resp.json()[\"agents\"]:\n print(agent[\"agent_name\"], agent[\"trace_count\"])" } ] } }, "/api/v1/agents/{agent_name}/topology": { "get": { "tags": [ "agents" ], "summary": "Get the multi-agent topology for an agent", "description": "Get the multi-agent topology for an agent.\n\nReturns:\n - orchestrator: the parent agent info\n - subagents: list of sub-agent nodes with drift status\n - edges: parent→child connections\n\nH1020: scoped to caller's org. Two orgs naming an agent the same name\nno longer see each other's manifests / traces / topology.", "operationId": "get_agent_topology_api_v1_agents__agent_name__topology_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/generate-prompts": { "post": { "tags": [ "agents" ], "summary": "Generate synthetic prompts for an agent", "description": "Generate synthetic prompts for an agent.\n\nBody (all optional):\n- count: number of prompts to generate (default 20, max 100)\n- categories: list of categories from [\"normal\", \"edge_cases\", \"multi_tool\", \"adversarial\"]", "operationId": "generate_prompts_api_v1_agents__agent_name__generate_prompts_post", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "default": {}, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/eval-policy": { "get": { "tags": [ "agents" ], "summary": "Get agent eval policy (deprecated)", "description": "DEPRECATED — Use GET /api/v1/evaluators?agent_name=... instead.", "operationId": "get_eval_policy_deprecated_api_v1_agents__agent_name__eval_policy_get", "deprecated": true, "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "agent_name": "my-agent", "deprecated": true, "message": "EvalPolicy is deprecated. Configure evaluators via /api/v1/evaluators." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "agents" ], "summary": "Upsert agent eval policy (deprecated)", "description": "DEPRECATED — Use POST /api/v1/evaluators instead.", "operationId": "upsert_eval_policy_deprecated_api_v1_agents__agent_name__eval_policy_put", "deprecated": true, "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "agent_name": "my-agent", "deprecated": true, "message": "EvalPolicy is deprecated. Configure evaluators via /api/v1/evaluators." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/eval-budget": { "get": { "tags": [ "agents" ], "summary": "Get per-agent eval budget (deprecated)", "description": "**Deprecated.** Per-agent budgets are no longer enforced — LLM-judge usage is tracked at the org level via billing. This endpoint returns a stub for backward compatibility and will be removed in a future release. Use `GET /api/v1/billing/usage` instead.", "operationId": "get_eval_budget_deprecated_api_v1_agents__agent_name__eval_budget_get", "deprecated": true, "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/skill-suggestions": { "get": { "tags": [ "agents" ], "summary": "CUJ-20 — rule-based skill suggestions for this agent", "description": "Run the CUJ-20 detectors and return a ranked list.\n\nSignals (each with structured `evidence` for the UI to render \"why\"):\n - `install` — uncovered tool calls (rule-based)\n - `remove` — menu-bloat skills (rule-based)\n - `install_category` — category gap relative to registry leaders (rule-based)\n - `install_rater` — skill the agent struggled without, per Skill\n Rater output (Phase 2 — evidence-based)\n\nOrg-scoped and agent-scoped. Empty list when nothing trips the\nthresholds — the UI renders a \"no suggestions right now\" placeholder\nrather than a fake recommendation.\n\nPhase 2 (2026-05-25): the rule-based detectors are joined by\nRater-driven recommendations, surfaced with the same response shape\nso the UI doesn't have to know they came from a different signal\nsource. Eventually the rule-based detectors deprecate; for now both\ncoexist and the Rater-driven ones rank higher when present.", "operationId": "get_skill_suggestions_api_v1_agents__agent_name__skill_suggestions_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "default": 8, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/subagent-health": { "get": { "tags": [ "agents" ], "summary": "Get health metrics for each sub-agent of an orchestrator", "description": "Get health metrics for each sub-agent of an orchestrator.\n\nReturns per-subagent: success rate, avg latency, error count, trace count,\nand drift status. Only includes sub-agents that appear in the orchestrator's\nlatest manifest as 'subagent' components or that have parent_trace_id links.\n\nQuery params:\n- days: lookback window (default 7)", "operationId": "get_subagent_health_api_v1_agents__agent_name__subagent_health_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 7, "title": "Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/delegation-stats": { "get": { "tags": [ "agents" ], "summary": "Get delegation analytics for an orchestrator agent", "description": "Get delegation analytics for an orchestrator agent.\n\nReturns:\n- frequency: per-subagent delegation count + percentage\n- per_trace: avg/max sub-agents per orchestrator trace\n- error_rate: fraction of traces with at least one child error\n- by_day: delegation count per day over the lookback window", "operationId": "get_delegation_stats_api_v1_agents__agent_name__delegation_stats_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/cost-trend": { "get": { "tags": [ "agents" ], "summary": "Daily token+cost trend for an agent over a lookback window", "description": "Return per-day {trace_count, total_tokens, total_cost_usd} for an agent.\n\nAggregates LlmCall rows for traces of this agent in the org over the\nlast `days` days; cost is computed via `pricing.estimate_cost` per call.\nUsed by the agent-detail cost burn-rate widget.", "operationId": "get_cost_trend_api_v1_agents__agent_name__cost_trend_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/compat-summary": { "get": { "tags": [ "agents" ], "summary": "Get compatibility summary for an agent's latest manifest transition", "description": "Get compatibility summary for an agent's latest manifest transition.\n\nReturns keep/repair/replay/drop counts, the manifest versions involved,\nand the overall recommended action. Used by `decimalai compat-check` CLI.\n\nIf a stored CompatibilityReport exists, returns it. Otherwise (or if\nrecompute=true), runs a fresh analysis.", "operationId": "get_compat_summary_api_v1_agents__agent_name__compat_summary_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "recompute", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force a fresh compatibility analysis", "default": false, "title": "Recompute" }, "description": "Force a fresh compatibility analysis" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/impact-report": { "get": { "tags": [ "agents" ], "summary": "Aggregate \"Impact Report\" for an agent — composes compat-summary", "description": "Aggregate Impact Report for an agent (CUJ-1 / BUG-004).\n\nReturns ONE response containing everything the frontend ImpactReport\nsurfaces, eliminating the count drift that came from composing\nmultiple endpoints client-side (UI-004). Includes:\n\n - surface_changes : diff of tools / prompts / models / etc.\n - compat_summary : per-trace keep/repair/replay/drop counts\n - affected_trace_count : canonical \"N traces\" number (sum of compat)\n - sample_traces : up to 10 trace IDs to drill into\n - severity / severity_reason : verdict from compute_impact\n - human_summary : single-line natural-language diff (CUJ-4)\n\nFor backward compat, the legacy compat-summary fields (`keep`, `repair`,\netc.), the `buckets` alias, and `manifest_count`/`trace_count` are\nstill included so existing callers don't break.", "operationId": "get_impact_report_api_v1_agents__agent_name__impact_report_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Manifest Id" } }, { "name": "baseline_manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Baseline Manifest Id" } }, { "name": "recompute", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Recompute" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}": { "delete": { "tags": [ "agents" ], "summary": "Cascade-delete an agent and all dependent data (TEST-001 fix)", "description": "Cascade-delete an agent and all dependent data (TEST-001 fix).\n\nIntended for test/cleanup flows. Safety guard: requires the agent name\nto begin with `__` (the smoke-test naming convention) OR for the agent\nto have fewer than 100 traces. This prevents accidental deletion of\nproduction agents from leaked test scripts.\n\nH1021: scoped by caller's org_id. Pre-fix, a valid API key from Org A\ncould DELETE Org B's traces+manifests by guessing the agent_name; the\ncascade had no tenant boundary. All discovery and cascade queries now\nfilter `.org_id == org_id` so the destructive operation is contained\nto the caller's own data.\n\nH1023 (batched): the unused `key_ctx: KeyContext` parameter (which\nreferenced an unimported name and would have failed mypy --strict)\nis replaced by the `org_id` dep above.", "operationId": "delete_agent_api_v1_agents__agent_name__delete", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/suggestions": { "get": { "tags": [ "agents" ], "summary": "Get contextual cross-pillar suggestions for an agent", "description": "Get contextual cross-pillar suggestions for an agent.\n\nEvaluates usage patterns and returns up to 3 suggestions for\nadjacent platform features the user hasn't discovered yet.", "operationId": "get_cross_pillar_suggestions_api_v1_agents__agent_name__suggestions_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Cross Pillar Suggestions Api V1 Agents Agent Name Suggestions Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/suggestions/global": { "get": { "tags": [ "agents" ], "summary": "Get org-wide cross-pillar suggestions (not scoped to any agent)", "description": "Get org-wide cross-pillar suggestions (not scoped to any agent).\n\nUsed by the home dashboard to show suggestions that span all agents.", "operationId": "get_global_suggestions_api_v1_agents_suggestions_global_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Global Suggestions Api V1 Agents Suggestions Global Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/rename": { "post": { "tags": [ "agents" ], "summary": "Rename an agent. The old name continues to resolve via the alias table.", "description": "Rename ``agent_name`` to ``payload[\"new_name\"]`` for the caller's org.\n\nWrites a forwarding alias so URLs that referenced the old name\nkeep working — ``resolve_agent_id`` checks ``agent_name_alias``\nwhen the primary lookup misses. See\n``app/services/agent_service.py::rename_agent``.", "operationId": "rename_agent_endpoint_api_v1_agents__agent_name__rename_post", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Renamed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Rename Agent Endpoint Api V1 Agents Agent Name Rename Post" } } } }, "400": { "description": "Invalid input or name clash." }, "404": { "description": "Agent not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/skills": { "get": { "tags": [ "agents" ], "summary": "List skills assigned to this agent", "description": "Return all skill subscriptions for the given agent.\n\nEach row includes the skill's identity + the pinned version (or null\nfor \"always latest\"). The skill's full metadata (description, body,\netc.) is not returned here — call `/api/v1/skills/{name}` for that.", "operationId": "list_agent_skills_api_v1_agents__agent_name__skills_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Agent Skills Api V1 Agents Agent Name Skills Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/skills/{skill_id}": { "post": { "tags": [ "agents" ], "summary": "Assign a skill to this agent (optionally pinned to a specific version)", "description": "Subscribe the agent to the skill, idempotent.\n\nRe-assigning an existing pair updates `pinned_version_id`. Equivalent\nto `POST /skills/{skill_name}/subscribe` but addressed by agent_name\n+ skill_id for the agent-centric workflow (e.g. a \"Skills\" tab on\nthe agent dashboard).", "operationId": "assign_skill_to_agent_api_v1_agents__agent_name__skills__skill_id__post", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "pin_version_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional skill_version.id to pin. Null = follow the skill's latest version.", "title": "Pin Version Id" }, "description": "Optional skill_version.id to pin. Null = follow the skill's latest version." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Assign Skill To Agent Api V1 Agents Agent Name Skills Skill Id Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agents" ], "summary": "Unassign a skill from this agent", "description": "Remove the (agent_name, skill_id) subscription.\n\nIdempotent: returns `{status: \"ok\", action: \"noop\"}` if there was\nnothing to remove.", "operationId": "unassign_skill_from_agent_api_v1_agents__agent_name__skills__skill_id__delete", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Unassign Skill From Agent Api V1 Agents Agent Name Skills Skill Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/annotations": { "post": { "tags": [ "annotations" ], "summary": "Add a human annotation/label to a trace", "description": "Add a human annotation/label to a trace.", "operationId": "create_annotation_api_v1_traces__trace_id__annotations_post", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "annotations" ], "summary": "Get all annotations for a specific trace", "description": "Get all annotations for a specific trace.", "operationId": "get_trace_annotations_api_v1_traces__trace_id__annotations_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/annotations/{annotation_id}": { "put": { "tags": [ "annotations" ], "summary": "Update an existing annotation", "description": "Update an existing annotation.", "operationId": "update_annotation_api_v1_annotations__annotation_id__put", "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "annotations" ], "summary": "Delete an annotation", "description": "Delete an annotation.", "operationId": "delete_annotation_api_v1_annotations__annotation_id__delete", "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/annotations/stats": { "get": { "tags": [ "annotations" ], "summary": "Get annotation label distribution and summary stats", "description": "Get annotation label distribution and summary stats.", "operationId": "get_annotation_stats_api_v1_annotations_stats_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/add-from-annotations": { "post": { "tags": [ "annotations" ], "summary": "Promote annotated traces into an eval dataset", "description": "Promote annotated traces into an eval dataset.\n\nGathers traces labeled with the specified label, extracts\ninput/expected_output pairs, and adds them as dataset examples.", "operationId": "promote_annotations_to_dataset_api_v1_datasets__dataset_id__add_from_annotations_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/audit-log": { "get": { "tags": [ "audit-log" ], "summary": "List recent admin actions — oncall 'what changed' surface", "description": "Return audit log rows for the calling org, newest first.\n\nCommon oncall query: `?since=&action=manifest.rollback&limit=20`\nanswers \"did anyone roll back a manifest in the last hour?\".\n\nAll filters are AND-combined. Org isolation is enforced via\n`require_org_scope`; no cross-tenant leak.", "operationId": "list_audit_log_api_v1_audit_log_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 timestamp; only entries newer than this are returned.", "title": "Since" }, "description": "ISO-8601 timestamp; only entries newer than this are returned." }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact action match (e.g., 'manifest.rollback').", "title": "Action" }, "description": "Exact action match (e.g., 'manifest.rollback')." }, { "name": "target_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by target_type (e.g., 'version_manifest').", "title": "Target Type" }, "description": "Filter by target_type (e.g., 'version_manifest')." }, { "name": "target_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by exact target_id.", "title": "Target Id" }, "description": "Filter by exact target_id." }, { "name": "actor_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by Clerk user id who performed the action.", "title": "Actor User Id" }, "description": "Filter by Clerk user id who performed the action." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Audit Log Api V1 Audit Log Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/models": { "get": { "tags": [ "auth" ], "summary": "List supported LLM models for the playground (improve#624)", "description": "Public enumeration of models the playground can route to. Optional `?provider=openai|gemini|anthropic` filter. Closes discovery/cuj25-playground-ux-researcher/no-models-discovery-endpoint.", "operationId": "list_models_api_v1_models_get", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Models Api V1 Models Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1": { "get": { "tags": [ "auth" ], "summary": "API root — HATEOAS-lite index (improve#618)", "description": "Returns a directory of top-level API resources. Lets newcomers self-discover endpoint categories without grepping /openapi.json. Closes discovery/cuj16_ml_intern_onboarding/no-api-root-index.", "operationId": "api_root_api_v1_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Api Root Api V1 Get" } } } } } } }, "/api/v1/me": { "get": { "tags": [ "auth" ], "summary": "Whoami — confirm key, see scope/permissions/org (improve#617)", "description": "Single-call confirmation that the caller's auth works + what it gives.\n\nReturns:\n key_prefix, scope, permissions, expires_at, last_used_at,\n org_id, org_name, plan, user (if Clerk JWT)\n\nUse this as your first call after getting an API key — if it\nreturns 200 you're authenticated, and the response shows what\norg/plan/permissions the key carries.", "operationId": "whoami_api_v1_me_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Whoami Api V1 Me Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/badges/{agent_name}/compat.svg": { "get": { "tags": [ "badges" ], "summary": "Compatibility-score badge (keep %) for an agent", "description": "Return an SVG badge of `keep%` from the agent's latest compat report.\n\n\"keep\" is the most user-friendly headline metric — it answers \"what %\nof my training data is still safe to use after the latest change?\"\nThe full keep/repair/replay/drop breakdown is on the agent detail page.", "operationId": "compat_badge_api_v1_badges__agent_name__compat_svg_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/plans": { "get": { "tags": [ "billing" ], "summary": "Get all available plans with limits and pricing", "description": "Get all available plans with limits and pricing.\n\nThis endpoint is public (no auth required) — it returns the same\ninformation shown on the marketing pricing page.", "operationId": "list_plans_api_v1_billing_plans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/billing/plan": { "get": { "tags": [ "billing" ], "summary": "Get current plan details and limits", "description": "Get current plan details and limits.", "operationId": "get_plan_api_v1_billing_plan_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/usage": { "get": { "tags": [ "billing" ], "summary": "Get usage for the current billing period", "description": "Get usage for the current billing period.", "operationId": "get_usage_api_v1_billing_usage_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "H1334 (improve#681): NOT supported on this endpoint. Billing counters are org-wide; per-workspace breakdown isn't computed. Providing this param returns 400 so callers don't silently get the org-wide totals they thought were workspace-scoped.", "title": "Workspace Id" }, "description": "H1334 (improve#681): NOT supported on this endpoint. Billing counters are org-wide; per-workspace breakdown isn't computed. Providing this param returns 400 so callers don't silently get the org-wide totals they thought were workspace-scoped." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/usage/history": { "get": { "tags": [ "billing" ], "summary": "Get usage history for the last N months (default 6)", "description": "Get usage history for the last N months (default 6).\n\nReturns a list of monthly usage summaries, most recent first.", "operationId": "get_usage_history_api_v1_billing_usage_history_get", "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 24, "minimum": 1, "description": "Number of months of history", "default": 6, "title": "Months" }, "description": "Number of months of history" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/usage/projection": { "get": { "tags": [ "billing" ], "summary": "Project current-period usage to end-of-month (audit#305)", "description": "Project current-period usage forward to end-of-month.\n\nReturns current_rate_per_day, projected_eom_usage, will_exceed,\ndays_to_limit. CUJ-finance / engineering-lead wants advance warning\nbefore hitting the 80% throttle, not at the throttle.", "operationId": "get_usage_projection_api_v1_billing_usage_projection_get", "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "type": "string", "description": "One of: traces, eval_judge, sft_rows, storage_bytes, regression_checks", "default": "traces", "title": "Dimension" }, "description": "One of: traces, eval_judge, sft_rows, storage_bytes, regression_checks" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/usage/history.csv": { "get": { "tags": [ "billing" ], "summary": "Download usage history as CSV (one row per period × dimension)", "description": "Same data as /usage/history but rendered as CSV — for finance teams\ndoing month-end reconciliation in Excel/Sheets. Header row:\nperiod, plan, dimension, used, limit, pct.", "operationId": "get_usage_history_csv_api_v1_billing_usage_history_csv_get", "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 24, "minimum": 1, "description": "Number of months of history", "default": 6, "title": "Months" }, "description": "Number of months of history" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/invoices": { "get": { "tags": [ "billing" ], "summary": "List recent Stripe invoices with PDF download links", "description": "List recent Stripe invoices for the current organization.\n\nUsed by CUJ-35 (finance persona) to reconcile invoices month-end.\nReturns an empty list when the org has no Stripe customer (free-tier\nor never-upgraded). 503 when Stripe is not configured.", "operationId": "list_invoices_api_v1_billing_invoices_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max invoices to return", "default": 12, "title": "Limit" }, "description": "Max invoices to return" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/invoices.zip": { "get": { "tags": [ "billing" ], "summary": "Download a ZIP archive of invoice PDFs + manifest for one year (year-end audit)", "description": "Bundle one calendar year of Stripe invoice PDFs + a CSV manifest\ninto a ZIP for year-end audit (closes audit#305 billing finding).\n\nManifest columns: invoice_number, date, amount_paid_usd, status,\nperiod_start, period_end, hosted_invoice_url, pdf_filename.\n\nReturns 503 when Stripe is not configured, 502 on Stripe API error,\nand 200 with an empty ZIP (just `manifest.csv` listing zero rows)\nwhen the org has no invoices in `year`.", "operationId": "download_invoices_archive_api_v1_billing_invoices_zip_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 2100, "minimum": 2000, "description": "Calendar year (e.g., 2026)", "title": "Year" }, "description": "Calendar year (e.g., 2026)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/checkout": { "post": { "tags": [ "billing" ], "summary": "Start a Stripe Checkout session for a plan upgrade", "description": "Start a Stripe Checkout session for a plan upgrade.\n\nBody: {\"plan\": \"core\" | \"pro\"}\n\nReturns: {\"checkout_url\": \"https://checkout.stripe.com/...\"}", "operationId": "create_checkout_api_v1_billing_checkout_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/portal": { "post": { "tags": [ "billing" ], "summary": "Get a Stripe Customer Portal URL for subscription management", "description": "Get a Stripe Customer Portal URL for subscription management.\n\nReturns: {\"portal_url\": \"https://billing.stripe.com/...\"}", "operationId": "billing_portal_api_v1_billing_portal_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/webhook": { "post": { "tags": [ "billing" ], "summary": "Handle incoming Stripe webhook events", "description": "Handle incoming Stripe webhook events.\n\nThis endpoint receives events from Stripe's webhook system. It verifies\nthe signature using the webhook secret, then routes to the appropriate\nhandler. No API key auth required — Stripe signs with its own secret.\n\nHandles:\n- checkout.session.completed → upgrade plan\n- invoice.payment_failed → start grace period\n- customer.subscription.deleted → downgrade to free\n- invoice.paid → confirm renewal, clear grace period", "operationId": "stripe_webhook_api_v1_billing_webhook_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid or missing Stripe-Signature header" }, "422": { "description": "Malformed JSON payload" } } } }, "/api/v1/registry/skills": { "get": { "tags": [ "registry" ], "summary": "Browse the public skills registry", "description": "Browse the public skills registry.\n\nNo authentication required. If authenticated, results include\n'installed_as' field showing if the user already has a fork.", "operationId": "browse_registry_api_v1_registry_skills_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search query (keyword or semantic)", "title": "Q" }, "description": "Search query (keyword or semantic)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tags to filter by", "title": "Tags" }, "description": "Comma-separated tags to filter by" }, { "name": "badge", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by badge: verified, featured, community, imported", "title": "Badge" }, "description": "Filter by badge: verified, featured, community, imported" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort by: recommended (SkillScore v2, evidence-tiered, ≥10 activations; alias: effectiveness), lift (verified benchmark lift; alias: biggest_improvement), popular (30d uses, installs tiebreak), installs, top_rated (AI live rating, ≥10 rated), efficiency (token savings), most_turn_savings, rating (legacy pass-rate), recent", "default": "recommended", "title": "Sort" }, "description": "Sort by: recommended (SkillScore v2, evidence-tiered, ≥10 activations; alias: effectiveness), lift (verified benchmark lift; alias: biggest_improvement), popular (30d uses, installs tiebreak), installs, top_rated (AI live rating, ≥10 rated), efficiency (token savings), most_turn_savings, rating (legacy pass-rate), recent" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination (last skill ID)", "title": "Cursor" }, "description": "Cursor for pagination (last skill ID)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "description": "Display view — 'grid' (default) or 'ranks' (Leaderboard: adds rank + rank_metric fields)", "default": "grid", "title": "View" }, "description": "Display view — 'grid' (default) or 'ranks' (Leaderboard: adds rank + rank_metric fields)" }, { "name": "include_unsafe", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include skills the safety scanner blocked (default false — malicious content is hidden)", "default": false, "title": "Include Unsafe" }, "description": "Include skills the safety scanner blocked (default false — malicious content is hidden)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "items": [ { "id": "sk_pub123", "name": "semantic-search", "description": "Semantic search over knowledge bases", "category": "retrieval", "stability": "stable", "visibility": "public", "avg_rating": 4.5, "install_count": 230, "effectiveness": { "skill_score": 0.85 }, "badge": "verified" } ], "total": 45 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\"https://api.decimal.ai/api/v1/registry/skills\",\n params={\"category\": \"retrieval\", \"sort\": \"effectiveness\"})\nresp.raise_for_status()\nprint(resp.json()[\"items\"]) # browse returns {\"items\": [...], \"next_cursor\": ...}" }, { "lang": "Bash", "label": "CLI", "source": "decimalai registry browse --category retrieval --sort effectiveness" } ] } }, "/api/v1/registry/skills/{skill_id}": { "get": { "tags": [ "registry" ], "summary": "Get a registry skill", "description": "Returns the full record for a public registry skill, including body markdown,\nattachments, SkillScore (evidence-tiered quality composite), and review summary.\n\nAccepts either the UUID id or the human-readable slug (``Skill.name``).\nNo authentication required — the registry is public.", "operationId": "get_registry_skill_api_v1_registry_skills__skill_id__get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "sk_pub123", "name": "semantic-search", "description": "Semantic search over knowledge bases", "category": "retrieval", "stability": "stable", "visibility": "public", "body_markdown": "## When to use\n\nUse this skill when the user is asking knowledge-base questions.", "attachments": [ { "name": "scripts/index.py", "size": 4210, "type": "script" }, { "name": "references/embedding-models.md", "size": 1820, "type": "reference" } ], "effectiveness": { "skill_score": 0.85, "avg_pass_rate": 0.92, "total_activations_30d": 1240 }, "install_count": 230, "avg_rating": 4.5, "review_count": 18, "publisher": "decimal-labs", "created_at": "2026-02-10T14:00:00Z", "updated_at": "2026-05-01T09:15:00Z" } } } }, "404": { "description": "Skill not found in the public registry." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\"https://api.decimal.ai/api/v1/registry/skills/sk_pub123\")\nresp.raise_for_status()\nskill = resp.json()\nprint(skill[\"name\"], (skill.get(\"effectiveness\") or {}).get(\"skill_score\"))" }, { "lang": "Bash", "label": "CLI", "source": "decimalai registry get sk_pub123" } ] } }, "/api/v1/registry/skills/{skill_id}/lineage": { "get": { "tags": [ "registry" ], "summary": "Fork lineage tree for a public registry skill", "description": "Returns the fork tree rooted at this public registry skill.\n\nWalks `forked_from_skill_id` reverse-recursively up to `max_depth`\nlevels. Each node carries the fork's `install_count`, so the caller\ncan identify \"popular forks\" — community-iterated variants the\noriginal author didn't write but consumers gravitate to.\n\nOnly public (`visibility='public'`) descendants are returned;\nprivate forks living in consumer orgs are excluded (privacy).\n\nWhy this exists: `install_count` is a scalar on the root; without\na lineage view, the long tail of community-iterated forks is\ninvisible. Once a popular fork (install_count ≥ N) exists, surfacing\nit gives consumers an alternative that's been validated.", "operationId": "get_registry_skill_lineage_api_v1_registry_skills__skill_id__lineage_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "max_depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "Recursion depth cap", "default": 5, "title": "Max Depth" }, "description": "Recursion depth cap" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/playground-run": { "post": { "tags": [ "registry" ], "summary": "Dry-run a hypothetical user message against a public registry skill (no auth, no LLM call)", "description": "Public dry-run for a registry skill. Mirrors the auth'd\n/api/v1/skills/{name}/playground-run but takes a public registry\nskill ID and skips the org-ownership check, so a visitor can\nsanity-check the trigger match + rendered body BEFORE installing.\n\nBody: { user_input: str, variables?: dict, version_number?: int }\nResponse shape matches the auth'd endpoint exactly so the UI can\nshare the result component.", "operationId": "registry_skill_playground_run_api_v1_registry_skills__skill_id__playground_run_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/versions/{version_number}": { "get": { "tags": [ "registry" ], "summary": "Fetch a specific version's body markdown for a public registry skill", "description": "Returns the body_markdown for a specific version of a public registry\nskill. No authentication required. Used to render version-to-version\ndiffs on the public detail page (CUJ-29 polish).", "operationId": "get_registry_skill_version_api_v1_registry_skills__skill_id__versions__version_number__get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "version_number", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version Number" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/eval": { "get": { "tags": [ "registry" ], "summary": "Get the latest eval.yaml for a public registry skill", "description": "Return the latest `eval.yaml` text for a public registry skill.\n\nAnonymous-readable. Mirrors the `/body` pattern: accepts UUID or\n`Skill.name` slug. 404 when the skill has no eval.yaml authored yet.\n\nUsed by `decimalai skills pull ` to fetch the eval suite\nalongside `SKILL.md` so a user can run `decimalai skills benchmark`\nagainst the local copy.", "operationId": "get_registry_skill_eval_api_v1_registry_skills__skill_id__eval_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx, yaml\n\nresp = httpx.get(\"https://api.decimal.ai/api/v1/registry/skills/gdpr-pii-classifier/eval\")\nresp.raise_for_status()\neval_data = yaml.safe_load(resp.json()[\"eval_yaml_text\"])\nprint(f\"{len(eval_data['cases'])} test cases\")" }, { "lang": "Bash", "label": "CLI", "source": "decimalai skills pull gdpr-pii-classifier # writes eval.yaml alongside SKILL.md" } ] } }, "/api/v1/registry/skills/{skill_id}/benchmark": { "get": { "tags": [ "registry" ], "summary": "Latest benchmark run + per-case results for a public registry skill", "description": "Anonymous-readable view of the publisher's latest benchmark run.\n\nReturns the SkillTestRun row + per-case `SkillTestCaseResult` rows\nwith the same Without/With/Δ comparison fields the authenticated\nBenchmarkTab uses. Visitor cannot trigger a new run — they only see\nwhat the publisher last ran.", "operationId": "get_registry_skill_benchmark_api_v1_registry_skills__skill_id__benchmark_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/live-traces": { "get": { "tags": [ "registry" ], "summary": "Cross-org production trace aggregations for a public registry skill", "description": "Anonymous-readable, privacy-safe Live Traces summary.\n\nAggregates effectiveness ratings + discoverability gap + top\npatterns across ALL forks of the source skill — never leaking\nper-org breakdowns. Effectively the public-tier equivalent of the\nauthenticated `/skills/{name}/live-traces-summary` endpoint.", "operationId": "get_registry_skill_live_traces_api_v1_registry_skills__skill_id__live_traces_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/leaderboard": { "get": { "tags": [ "registry" ], "summary": "Public Skills Leaderboard — ranked by performance dimension within a window", "description": "Anonymous-readable, time-windowed ranked leaderboard.\n\nDistinct from the registry browse endpoint:\n - Registry `/skills?sort=` is about exploration (filter + paginate)\n - This endpoint is about ranking (top N by performance dimension)\n\nAxes (skill_scores_redesign §7.7 — every axis is an *earned place*,\nthe gate is stated in the UI sub-copy):\n - `skill_score`: SkillScore v2 DESC, full evidence only (≥2 legs) —\n provisional scores never chart. Rolling 30d rollup, so\n `window_days` does not apply to this axis.\n - `biggest_improvement`: latest verified SkillTestRun in the window,\n pass-rate delta vs the no-skill baseline.\n - `efficiency`: token savings ASC (most negative = cheapest); skills\n that INCREASED token cost are excluded. `most_turn_savings` is the\n legacy param for the turns-keyed variant and keeps working.\n - `top_rated`: SkillRaterReport mean in the window, ≥10 rated traces\n (matches the v2 rater-leg gate).", "operationId": "get_leaderboard_api_v1_registry_leaderboard_get", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "skill_score | biggest_improvement | efficiency | top_rated (legacy: most_turn_savings)", "default": "biggest_improvement", "title": "Sort" }, "description": "skill_score | biggest_improvement | efficiency | top_rated (legacy: most_turn_savings)" }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 3650, "minimum": 1, "description": "Time window (≤3650 ≈ 'all time')", "default": 30, "title": "Window Days" }, "description": "Time window (≤3650 ≈ 'all time')" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/activations": { "get": { "tags": [ "registry" ], "summary": "Usage time-series for a public registry skill (npm-style chart data)", "description": "Returns a multi-series usage time-series for a public registry skill,\nsummed across all consuming orgs' forks. The npm-style chart on the\npublic detail page reads from this.\n\nNo authentication required. Privacy-preserving: rolls up across orgs,\nno per-org breakdown. Zero-filled buckets so the chart can render\nwithout gap handling.\n\nResponse shape:\n {\n \"skill_id\": \"...\",\n \"window_days\": 30,\n \"bucket\": \"day\",\n \"series\": [\n {\"date\": \"2026-05-01\", \"activations\": 42,\n \"distinct_orgs\": 8, \"router_decisions\": 100, \"router_activated\": 70},\n ...\n ],\n \"totals\": {\"activations\": 1240, \"distinct_orgs_max\": 19, ...},\n }", "operationId": "get_registry_skill_activations_api_v1_registry_skills__skill_id__activations_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "description": "Trailing window in days (max 365)", "default": 30, "title": "Window Days" }, "description": "Trailing window in days (max 365)" }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "description": "Bucket granularity: day | week | month", "default": "day", "title": "Bucket" }, "description": "Bucket granularity: day | week | month" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated optional series. Supported values: `distinct_orgs`, `router_decisions`, `router_activated`. The base `activations` series is always returned.", "default": "", "title": "Include" }, "description": "Comma-separated optional series. Supported values: `distinct_orgs`, `router_decisions`, `router_activated`. The base `activations` series is always returned." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/install": { "post": { "tags": [ "registry" ], "summary": "Deprecated alias of /fork — kept for back-compat", "description": "Forks a public registry skill into your organization. The forked skill is\nfully owned by your org — edits do not affect the public version.\n\nPre-checks:\n1. Skill exists and is public\n2. User hasn't already forked this skill\n3. Name doesn't conflict with existing skills in the org", "operationId": "install_registry_skill_api_v1_registry_skills__skill_id__install_post", "deprecated": true, "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "new_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom name for the fork (optional)", "title": "New Name" }, "description": "Custom name for the fork (optional)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "installed_skill_id": "sk_local123", "source_skill_id": "sk_pub123", "name": "semantic-search", "version": 1 } } } }, "404": { "description": "Registry skill not found." }, "409": { "description": "Already forked in this org (idempotent — safe to retry)." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/fork": { "post": { "tags": [ "registry" ], "summary": "Fork a registry skill into your workspace", "description": "Forks a public registry skill into your organization. The forked skill is\nfully owned by your org — edits do not affect the public version.\n\nPre-checks:\n1. Skill exists and is public\n2. User hasn't already forked this skill\n3. Name doesn't conflict with existing skills in the org", "operationId": "fork_registry_skill_api_v1_registry_skills__skill_id__fork_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "new_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom name for the fork (optional)", "title": "New Name" }, "description": "Custom name for the fork (optional)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "installed_skill_id": "sk_local123", "source_skill_id": "sk_pub123", "name": "semantic-search", "version": 1 } } } }, "404": { "description": "Registry skill not found." }, "409": { "description": "Already forked in this org (idempotent — safe to retry)." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/registry/skills/sk_pub123/fork\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nprint(resp.json())" }, { "lang": "Bash", "label": "CLI", "source": "decimalai skills install sk_pub123" } ] } }, "/api/v1/registry/skills/{skill_id}/use": { "post": { "tags": [ "registry" ], "summary": "Use a registry skill — a linked pointer, not a copy", "description": "Link a public registry skill into your workspace *live* (no fork).\n\nCreates a ``Use`` pointer (``skill_subscription`` row) the resolver serves to your\nagents at the resolved version. ``scope='workspace'`` → one pointer for every agent;\n``scope='agent'`` → one per name in ``agents``. ``mode='latest'`` tracks the newest\nsafe upstream version; ``'pinned'`` freezes ``version``. Distinct from ``/fork`` (an\nowned, editable copy) — see the Use-vs-Fork spec.", "operationId": "use_registry_skill_api_v1_registry_skills__skill_id__use_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "description": "'workspace' (every agent) or 'agent'", "default": "workspace", "title": "Scope" }, "description": "'workspace' (every agent) or 'agent'" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "description": "'latest' (track newest safe) or 'pinned'", "default": "latest", "title": "Mode" }, "description": "'latest' (track newest safe) or 'pinned'" }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version id to pin when mode='pinned'", "title": "Version" }, "description": "Version id to pin when mode='pinned'" }, { "name": "agents", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated agent names when scope='agent'", "title": "Agents" }, "description": "Comma-separated agent names when scope='agent'" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Use pointer(s) created/updated.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad scope/mode/version." }, "404": { "description": "Public registry skill not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/rate": { "post": { "tags": [ "registry" ], "summary": "Rate a registry skill", "description": "Rate a registry skill. User must have forked it first.", "operationId": "rate_registry_skill_api_v1_registry_skills__skill_id__rate_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "rating", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 5, "minimum": 1, "description": "Rating 1-5", "title": "Rating" }, "description": "Rating 1-5" }, { "name": "review_text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Review Text" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "skill_id": "sk_pub123", "rating": 5, "new_avg": 4.6 } } } }, "403": { "description": "Caller hasn't forked this skill yet." }, "404": { "description": "Registry skill not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/registry/skills/sk_pub123/rate\",\n params={\"rating\": 5, \"review_text\": \"Solid skill, used in production.\"},\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()" }, { "lang": "Bash", "label": "CLI", "source": "decimalai registry rate sk_pub123 --rating 5" } ] } }, "/api/v1/registry/skills/{skill_id}/attachments": { "get": { "tags": [ "registry" ], "summary": "List attachments for a public registry skill", "description": "List attachments for a public registry skill.\n\nNo authentication required. Returns file metadata (not content)\nfor preview in the registry detail page.", "operationId": "list_registry_skill_attachments_api_v1_registry_skills__skill_id__attachments_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "directory", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by directory", "title": "Directory" }, "description": "Filter by directory" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/attachments/{attachment_id}": { "get": { "tags": [ "registry" ], "summary": "Get a single attachment with content for a public registry skill", "description": "Get a single attachment with content for a public registry skill.\n\nNo authentication required. Allows users to preview scripts\nand references before installing.", "operationId": "get_registry_skill_attachment_api_v1_registry_skills__skill_id__attachments__attachment_id__get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Attachment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/set-badge": { "post": { "tags": [ "registry" ], "summary": "Set the registry badge on a public skill (admin only)", "description": "Set the registry badge on a public skill (admin only).\n\nThis is how the DecimalAI team promotes skills to 'verified' (Official)\nor 'featured'. The badge determines how the skill appears in the registry\nUI and whether the auto-promotion scheduler will modify it.\n\nBadge behavior:\n- 'verified': Displayed as \"✓ Official\". Never auto-demoted by the scheduler.\n- 'featured': Displayed as \"★ Featured\". Can be auto-promoted/demoted.\n- 'community': Default badge for community-published skills.\n- 'imported': Default badge for GitHub-imported skills.", "operationId": "set_skill_badge_api_v1_registry_skills__skill_id__set_badge_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "badge", "in": "query", "required": true, "schema": { "type": "string", "description": "Badge value: verified, featured, community, imported", "title": "Badge" }, "description": "Badge value: verified, featured, community, imported" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{skill_id}/set-author": { "post": { "tags": [ "registry" ], "summary": "Set the author display name on a registry skill (admin only)", "description": "Set the author display name on a registry skill (admin only).\n\nUsed to brand official skills as 'DecimalAI' or correct author names.", "operationId": "set_registry_author_api_v1_registry_skills__skill_id__set_author_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "author_display_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Author name shown in registry", "title": "Author Display Name" }, "description": "Author name shown in registry" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/registry/skills/{name}/badge.svg": { "get": { "tags": [ "registry" ], "summary": "Public verified-lift SVG badge for a registry skill (README embed)", "description": "Anonymous SVG badge of a skill's verified lift + the model it was\nmeasured on, e.g. ``decimalai | +62% · gemini-3.5-flash``.\n\nNo verified benchmark / no measured lift → neutral ``unmeasured`` badge.\nNever fabricates a number. Always returns 200 with an SVG so the README\nimage tag never shows a broken-image icon, even for an unknown slug.", "operationId": "skill_lift_badge_api_v1_registry_skills__name__badge_svg_get", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "image/svg+xml": {} } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/changelog": { "get": { "tags": [ "changelog" ], "summary": "Workspace-wide activity feed (manifests, regressions, audit, training)", "description": "Return up to `limit` recent events newest-first for the caller's org.", "operationId": "list_changelog_api_v1_changelog_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO datetime — only events after this", "title": "Since" }, "description": "ISO datetime — only events after this" }, { "name": "types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated subset of: manifest,regression,audit,training", "title": "Types" }, "description": "Comma-separated subset of: manifest,regression,audit,training" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include events for platform-harness fixture agents (\\_\\_*, live-*, cuj*, …). Off by default — the activity feed was 100% CUJ-manifest spam in workspaces where the harness runs (deep audit 2026-06-10).", "default": false, "title": "Include Fixtures" }, "description": "When true, include events for platform-harness fixture agents (\\_\\_*, live-*, cuj*, …). Off by default — the activity feed was 100% CUJ-manifest spam in workspaces where the harness runs (deep audit 2026-06-10)." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Changelog Api V1 Changelog Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/violations": { "get": { "tags": [ "contract-violations" ], "summary": "List contract violations detected for a trace", "description": "Return all contract violations persisted for this trace.\n\nReturns an empty list (not 404) for traces that exist but had no\nviolations detected. Returns 404 only when the trace ID itself doesn't\nexist or belongs to another org.", "operationId": "list_trace_violations_api_v1_traces__trace_id__violations_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Trace Violations Api V1 Traces Trace Id Violations Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/violations": { "get": { "tags": [ "contract-violations" ], "summary": "Paginated list of contract violations for an agent", "description": "List violations for an agent within a time window (default last 24h).", "operationId": "list_agent_violations_api_v1_agents__agent_name__violations_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO-8601 timestamp. Defaults to 24h ago.", "title": "Since" }, "description": "ISO-8601 timestamp. Defaults to 24h ago." }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single violation kind", "title": "Kind" }, "description": "Filter to a single violation kind" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Agent Violations Api V1 Agents Agent Name Violations Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/violations/summary": { "get": { "tags": [ "contract-violations" ], "summary": "Aggregate violation counts for an agent dashboard", "description": "Total + per-kind breakdown for last 24h and last 7d.\n\nUsed by the AgentContractHealth dashboard strip (refresh TTL: 30s).\nReturns zero counts (not 404) for agents that exist but have no violations.", "operationId": "violation_summary_api_v1_agents__agent_name__violations_summary_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Violation Summary Api V1 Agents Agent Name Violations Summary Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/contract-mode/preview": { "get": { "tags": [ "contract-violations" ], "summary": "Preview what would fire if this agent were in closed-world mode", "description": "Run the contract checker in simulation against the last 7d of traces.\n\nFor descriptive-mode agents only. Returns ``is_closed_world: true`` and\nempty counts for agents that are already closed-world — the dashboard\nbanner hides itself in that case.\n\nPure read-only simulation: no rows are persisted. The 7-day window matches\nthe banner copy (\"In the last 7 days, N violations would have fired…\").\n\nHard cap: 1000 traces sampled. For agents producing more than ~140\ntraces/day this is the most-recent slice; the preview is a \"directional\nestimate,\" not an exhaustive scan.", "operationId": "contract_mode_preview_api_v1_agents__agent_name__contract_mode_preview_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Contract Mode Preview Api V1 Agents Agent Name Contract Mode Preview Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/costs": { "get": { "tags": [ "costs" ], "summary": "Workspace-wide LLM cost analytics", "description": "Returns totals + by_agent + by_model + by_day rollups.\n\nWindow capped at 180 days to keep the query bounded. For longer\nhorizons, a daily-rollup materialization would be required.", "operationId": "get_costs_api_v1_costs_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include platform-harness fixture agents (\\_\\_*, live-*, cuj*, …) in the spend aggregates. Off by default.", "default": false, "title": "Include Fixtures" }, "description": "When true, include platform-harness fixture agents (\\_\\_*, live-*, cuj*, …) in the spend aggregates. Off by default." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Costs Api V1 Costs Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets": { "post": { "tags": [ "datasets" ], "summary": "Create a dataset", "description": "Create a new dataset.\n\nSupports `X-Idempotency-Key` for safe retries — within 60s, a request with\nthe same key returns the original response instead of creating a duplicate.", "operationId": "create_dataset_api_v1_datasets_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Idempotency-Key" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "dataset_id": "ds_abc123", "name": "my-sft-data", "dataset_type": "sft" } } } }, "400": { "description": "`name` is required." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/datasets\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n json={\"name\": \"my-sft-data\", \"dataset_type\": \"sft\", \"training_target_agent\": \"my-agent\"},\n)\nresp.raise_for_status()\nprint(resp.json()[\"dataset_id\"])" } ] }, "get": { "tags": [ "datasets" ], "summary": "List datasets", "description": "List datasets, optionally filtered by target agent.", "operationId": "list_datasets_api_v1_datasets_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include datasets targeting platform-harness fixture agents (selftest-*, \\_\\_*, cuj*, …). Off by default.", "default": false, "title": "Include Fixtures" }, "description": "When true, include datasets targeting platform-harness fixture agents (selftest-*, \\_\\_*, cuj*, …). Off by default." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "datasets": [ { "id": "ds_001", "name": "travel-sft-v2", "dataset_type": "sft", "description": "Successful flight booking traces.", "training_target_agent": "travel-planner", "current_version_id": "dv_001", "manifest_id": "mfst_001", "created_at": "2026-04-01T12:00:00Z", "row_count": 1250, "version_count": 1 } ], "total": 3 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/datasets\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nfor ds in resp.json()[\"datasets\"]:\n print(ds[\"name\"], ds[\"row_count\"])" }, { "lang": "Bash", "label": "CLI", "source": "decimalai datasets list" } ] } }, "/api/v1/datasets/compat-buckets": { "get": { "tags": [ "datasets" ], "summary": "Manifest compatibility buckets for the dataset-create modal", "description": "Keep/repair/replay/drop counts for traces relative to a target manifest.\n\nPowers the bucket bar in the \"Create New Dataset\" modal. The counts mirror\nthe manifest-driven build selection exactly: keep + repair is the set the\nbuild includes. ``computed: false`` means no verdicts exist yet — the UI\noffers a \"Compute compatibility\" step that runs the classifier.", "operationId": "get_compat_buckets_api_v1_datasets_compat_buckets_get", "parameters": [ { "name": "target_manifest_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Manifest to bucket traces against", "title": "Target Manifest Id" }, "description": "Manifest to bucket traces against" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}": { "get": { "tags": [ "datasets" ], "summary": "Get a dataset", "description": "Get dataset detail with versions.", "operationId": "get_dataset_api_v1_datasets__dataset_id__get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "ds_abc123", "name": "travel-sft-v2", "dataset_type": "sft", "description": "Successful flight booking traces.", "training_target_agent": "travel-planner", "training_target_model": "gpt-4o", "current_version_id": "dv_001", "versions": [ { "id": "dv_001", "version_number": 1, "status": "ready", "row_count": 1250, "storage_format": "jsonl", "source_breakdown": { "keep": 1100, "repair": 150 }, "created_at": "2026-04-01T12:00:00Z" } ] } } } }, "404": { "description": "Dataset not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/datasets/ds_abc123\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nds = resp.json()" }, { "lang": "Bash", "label": "CLI", "source": "decimalai datasets show ds_abc123" } ] } }, "/api/v1/datasets/{dataset_id}/build": { "post": { "tags": [ "datasets" ], "summary": "Build a new dataset version from traces", "description": "Build a new dataset version from traces.", "operationId": "build_version_api_v1_datasets__dataset_id__build_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "version_id": "dv_002", "version_number": 2, "row_count": 1250, "version_status": "ready", "quality_report": { "avg_score": 0.87, "drop_rate": 0.05 } } } } }, "402": { "description": "Plan SFT-row quota exhausted." }, "404": { "description": "Dataset not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/datasets/ds_abc123/build\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n json={\"allowed_verdicts\": [\"keep\"], \"min_eval_score\": 0.7},\n)\nresp.raise_for_status()\nprint(resp.json()[\"version_id\"], resp.json()[\"row_count\"])" }, { "lang": "Bash", "label": "CLI", "source": "decimalai datasets build ds_abc123 --verdict keep" } ] } }, "/api/v1/datasets/{dataset_id}/versions/{version_id}/export": { "get": { "tags": [ "datasets" ], "summary": "Export a dataset version", "description": "Export a dataset version as JSONL or Parquet.", "operationId": "export_version_api_v1_datasets__dataset_id__versions__version_id__export_get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Export format: jsonl or parquet", "default": "jsonl", "title": "Format" }, "description": "Export format: jsonl or parquet" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "dataset_id": "ds_abc123", "version_id": "dv_001", "format": "openai_sft", "row_count": 1250, "rows": [ { "messages": [ { "role": "user", "content": "Find flights to Tokyo" }, { "role": "assistant", "content": "I found 3 flights..." } ] } ] } } } }, "404": { "description": "Dataset version not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\n\n# pull_dataset downloads + materializes a dataset version as a HuggingFace Dataset.\nds = decimalai.pull_dataset(\n api_key=\"dai_sk_...\",\n dataset_id=\"ds_abc123\",\n version_id=\"dv_001\",\n)\nprint(f\"{len(ds)} rows\")" }, { "lang": "Bash", "label": "CLI", "source": "decimalai datasets export ds_abc123 dv_001 --format openai_sft -o out.jsonl" } ] } }, "/api/v1/datasets/{dataset_id}/versions/{version_id}/quality-stats": { "get": { "tags": [ "datasets" ], "summary": "Get quality statistics for a dataset version", "description": "Get quality statistics for a dataset version.\n\nReturns eval score distribution histogram, split breakdown,\nmessage length stats, tool usage, and verdict distribution.", "operationId": "get_version_quality_stats_api_v1_datasets__dataset_id__versions__version_id__quality_stats_get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/versions/{version_id}/validate": { "post": { "tags": [ "datasets" ], "summary": "Validate a dataset version quality for CI gates", "description": "Validate a dataset version quality for CI gates.\n\nReturns a pass/fail result based on quality thresholds:\n- min_quality_avg: minimum average eval score across all examples\n- required_verdicts: only these verdicts are acceptable\n- min_row_count: minimum number of rows expected", "operationId": "validate_version_api_v1_datasets__dataset_id__versions__version_id__validate_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "default": {}, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/versions/{version_id}/compare/{compare_version_id}": { "get": { "tags": [ "datasets" ], "summary": "Compare two dataset versions side-by-side", "description": "Compare two dataset versions side-by-side.\n\nReturns row-level diffs: added, removed, and modified examples.", "operationId": "compare_versions_api_v1_datasets__dataset_id__versions__version_id__compare__compare_version_id__get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "compare_version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Compare Version Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/versions/{version_id}/quality": { "patch": { "tags": [ "datasets" ], "summary": "Update the quality review status of a dataset version", "description": "Update the quality review status of a dataset version.\n\nBody:\n quality_status: \"pending_review\" | \"approved\" | \"rejected\" | \"needs_revision\"\n reviewer: reviewer identity\n notes: optional review notes", "operationId": "update_quality_status_api_v1_datasets__dataset_id__versions__version_id__quality_patch", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/eval-scores": { "post": { "tags": [ "eval-scores" ], "summary": "Push external evaluation scores", "description": "Push evaluation scores from an external system (DeepEval, LangSmith, etc.).\n\nScores are stored as quality scores (category=\"quality\") and combined with\nbuilt-in compatibility scores in the unified decision engine.\n\nIf a score with the same (trace_id, name, source) already exists, it is\nupdated (upsert behavior).", "operationId": "push_eval_scores_api_v1_traces__trace_id__eval_scores_post", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushScoresRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushScoresResponse" }, "example": { "trace_id": "trc_abc123", "source": "deepeval", "scores_stored": 2, "scores": [ { "id": "es_001", "name": "correctness", "score": 0.9, "passed": true, "source": "deepeval", "category": "quality" }, { "id": "es_002", "name": "faithfulness", "score": 0.85, "passed": true, "source": "deepeval", "category": "quality" } ] } } } }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "# For DeepEval / LangSmith integrations, prefer the dedicated helpers:\n# decimalai.push_deepeval_results(trace_id=..., results=...)\n# decimalai.push_langsmith_scores(trace_id=..., feedback=...)\n# Generic custom scores:\nimport decimalai\n\ndecimalai.push_custom_scores(\n api_key=\"dai_sk_...\",\n trace_id=\"trc_abc123\",\n source=\"my-pipeline\",\n scores=[\n {\"name\": \"correctness\", \"score\": 0.9},\n {\"name\": \"faithfulness\", \"score\": 0.85},\n ],\n)" } ] }, "get": { "tags": [ "eval-scores" ], "summary": "Get all evaluation scores for a trace", "description": "Get all evaluation scores (quality + compatibility) for a trace.\n\nReturns scores grouped by category with aggregate values.", "operationId": "get_eval_scores_api_v1_traces__trace_id__eval_scores_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScoresResponse" }, "example": { "trace_id": "trc_abc123", "quality_scores": [ { "id": "es_001", "name": "correctness", "score": 0.9, "passed": true, "source": "deepeval", "category": "quality" } ], "compatibility_scores": [], "aggregate_quality": 0.9 } } } }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/traces/trc_abc123/eval-scores\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nscores = resp.json()" } ] } }, "/api/v1/traces/{trace_id}/eval-breakdown": { "get": { "tags": [ "eval-scores" ], "summary": "Get full eval breakdown with provenance", "description": "Get the full eval breakdown for a trace, grouped by source.\n\nShows every score with its provenance (source label, icon, badge color),\ngrouped into SourceGroups for the frontend to render section-by-section.\nIncludes decision reasons explaining how the final verdict was determined.", "operationId": "get_eval_breakdown_api_v1_traces__trace_id__eval_breakdown_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalBreakdownResponse" } } } }, "400": { "description": "Malformed trace_id (not a UUID)." }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\n\n# get_eval_breakdown is a top-level SDK function.\nbreakdown = decimalai.get_eval_breakdown(\n api_key=\"dai_sk_...\",\n trace_id=\"trc_abc123\",\n)\nfor group in breakdown[\"source_groups\"]:\n print(group[\"source_label\"], group[\"source_avg\"])" } ] } }, "/api/v1/traces/{trace_id}/decision": { "post": { "tags": [ "eval-scores" ], "summary": "Compute unified verdict for a trace", "description": "Compute and persist the unified verdict for a trace.\n\nAggregates all quality and compatibility EvalScore rows into a single\nactionable verdict: keep / repair / replay / drop.", "operationId": "compute_trace_decision_api_v1_traces__trace_id__decision_post", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" }, "example": { "trace_id": "trc_abc123", "verdict": "keep", "quality_avg": 0.88, "compat_avg": 0.95, "quality_scores": [], "compat_scores": [], "reasons": [ "All quality scores above threshold." ] } } } }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/traces/trc_abc123/decision\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nprint(resp.json()[\"verdict\"]) # 'keep' | 'repair' | 'replay' | 'drop'" } ] } }, "/api/v1/traces/batch-decision": { "post": { "tags": [ "eval-scores" ], "summary": "Batch compute unified verdicts", "description": "Batch compute unified verdicts for multiple traces.\n\nProvide either trace_ids or manifest_id (to score all traces from that manifest).", "operationId": "batch_decision_api_v1_traces_batch_decision_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDecisionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDecisionResponse" }, "example": { "decisions": [ { "trace_id": "trc_001", "verdict": "keep", "quality_avg": 0.92, "compat_avg": 0.95, "quality_scores": [], "compat_scores": [], "reasons": [] } ], "total": 1, "verdict_counts": { "keep": 1, "repair": 0, "replay": 0, "drop": 0 } } } } }, "400": { "description": "Either `trace_ids` or `manifest_id` is required." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\n# Score every trace from a manifest in one call.\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/traces/batch-decision\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n json={\"manifest_id\": \"mfst_abc123\"},\n)\nresp.raise_for_status()\nprint(resp.json()[\"verdict_counts\"])" } ] } }, "/api/v1/eval-scores.csv": { "get": { "tags": [ "eval-scores" ], "summary": "Download all eval scores for the org as CSV (audit, offline review).", "description": "Stream EvalScore rows for the caller's org as CSV.\n\nColumns: trace_id, agent_name, evaluator (name), category, source,\nscore, passed, reason, created_at. Optional filters:\n- since_hours: only rows where the trace was created within the last N hours.\n- agent: only rows for traces of a specific agent.\n\nOrg-scoping is enforced by JOIN-filtering on `run_trace.org_id == ctx.org_id`.\nReturns text/csv with a `Content-Disposition: attachment` so browsers save.", "operationId": "export_eval_scores_csv_api_v1_eval_scores_csv_get", "parameters": [ { "name": "since_hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Since Hours" } }, { "name": "agent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/templates": { "get": { "tags": [ "evaluators" ], "summary": "List available evaluator templates with category metadata", "description": "List available evaluator templates with category metadata.\n\nReturns templates grouped by category with icons and descriptions.\nNo billing impact — templates are just definitions.", "operationId": "get_templates_api_v1_evaluators_templates_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Templates Api V1 Evaluators Templates Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators": { "get": { "tags": [ "evaluators" ], "summary": "List evaluators configured for an agent (or org-wide defaults)", "description": "List evaluators configured for an agent (or org-wide defaults).", "operationId": "list_evaluators_api_v1_evaluators_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Evaluators Api V1 Evaluators Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "evaluators" ], "summary": "Create a new evaluator from a template or custom config", "description": "Create a new evaluator from a template or custom config.\n\nBody:\n template_id: str (optional) — use a built-in template\n agent_name: str (optional) — attach to specific agent\n name: str — evaluator name\n display_name: str (optional)\n description: str (optional)\n eval_type: \"deterministic\" | \"llm_judge\" | \"external\"\n category: \"quality\" | \"safety\" | \"rag\" | \"agentic\" | \"custom\"\n prompt_template: str (optional) — for llm_judge type\n threshold: float (optional, default 0.5)\n enabled: bool (optional, default true)", "operationId": "create_evaluator_api_v1_evaluators_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Evaluator Api V1 Evaluators Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/register": { "post": { "tags": [ "evaluators" ], "summary": "Register SDK-defined evaluators discovered via @eval decorator", "description": "Register SDK-defined evaluators discovered via @eval decorator.\n\nIdempotent — repeated calls upsert by (name, agent_name, org_id).\nSets definition_source=\"sdk\" and eval_type=\"external\" so scores pushed\nlater via /traces/{id}/eval-scores or embedded on traces are linked\nto the registered evaluator.\n\nBody:\n evaluators: [\n {\n name: str (required),\n category: str (default \"quality\"),\n description: str (optional),\n source_location: str (optional, \"path/to/file.py:42\"),\n agent_name: str (optional — null means org-wide),\n },\n ...\n ]", "operationId": "register_sdk_evaluators_api_v1_evaluators_register_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Register Sdk Evaluators Api V1 Evaluators Register Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/suggestions": { "get": { "tags": [ "evaluators" ], "summary": "Auto-suggested evaluators based on recent trace patterns", "description": "Returns prebuilt evaluators the workspace would benefit from,\nbased on heuristic analysis of recent trace patterns (G-6).\n\nCheap (no LLM call); safe to render on every /evaluate page load.", "operationId": "get_evaluator_suggestions_api_v1_evaluators_suggestions_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Evaluator Suggestions Api V1 Evaluators Suggestions Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/coverage": { "get": { "tags": [ "evaluators" ], "summary": "Cross-agent coverage matrix", "description": "Cross-agent coverage matrix.\n\nReturns per-agent rows with quality scores grouped by category and\na compat keep_rate. Powers the /evaluate page coverage matrix.", "operationId": "get_evaluator_coverage_api_v1_evaluators_coverage_get", "parameters": [ { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "DQ-18 (2026-06-06): when False (default), hide fixture agents (__*, _benchmark__*, loop_test_*, soak-*, selftest-*) from the coverage matrix — the same predicate /agents applies. cuj15 found __cuj*/selftest-* rows polluting the matrix at improve#1441. Set True for debugging/admin tooling.", "default": false, "title": "Include Fixtures" }, "description": "DQ-18 (2026-06-06): when False (default), hide fixture agents (__*, _benchmark__*, loop_test_*, soak-*, selftest-*) from the coverage matrix — the same predicate /agents applies. cuj15 found __cuj*/selftest-* rows polluting the matrix at improve#1441. Set True for debugging/admin tooling." }, { "name": "window_days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "When set, attach a per-cell `pass_rate_delta`: the pass-rate over the most recent `window_days` minus the pass-rate over the prior equal window. Omit (default) for the all-time matrix with no delta — keeps the legacy /evaluate v1 path unchanged.", "title": "Window Days" }, "description": "When set, attach a per-cell `pass_rate_delta`: the pass-rate over the most recent `window_days` minus the pass-rate over the prior equal window. Omit (default) for the all-time matrix with no delta — keeps the legacy /evaluate v1 path unchanged." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Evaluator Coverage Api V1 Evaluators Coverage Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/{evaluator_id}": { "patch": { "tags": [ "evaluators" ], "summary": "Update an evaluator's configuration.\"\"\"", "description": "Update an evaluator's configuration.\n\n**Prompt versioning (improve#638):** if `prompt_template` is mutated\nAND the new value differs from the current one, a new\n`EvaluatorVersion` snapshot row is appended BEFORE the in-place\nupdate. This preserves history so historical eval-scores can be\nreproduced against the prompt that actually produced them.\nCloses part of audit/improvements/improvement-evals-evaluator-versioning.", "operationId": "update_evaluator_api_v1_evaluators__evaluator_id__patch", "parameters": [ { "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluator Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Evaluator Api V1 Evaluators Evaluator Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "evaluators" ], "summary": "Delete an evaluator", "description": "Delete an evaluator.", "operationId": "delete_evaluator_api_v1_evaluators__evaluator_id__delete", "parameters": [ { "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluator Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Delete Evaluator Api V1 Evaluators Evaluator Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/{evaluator_id}/versions": { "get": { "tags": [ "evaluators" ], "summary": "List prompt-template versions for an evaluator (improve#638)", "description": "Return the version history of an evaluator's prompt_template.\n\nOrder: newest first. Each entry includes prompt_template +\nchange_reason + created_at + created_by_user_id. Closes part of\naudit/improvements/improvement-evals-evaluator-versioning.", "operationId": "list_evaluator_versions_api_v1_evaluators__evaluator_id__versions_get", "parameters": [ { "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluator Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Evaluator Versions Api V1 Evaluators Evaluator Id Versions Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/{evaluator_id}/pass-rate-trend": { "get": { "tags": [ "evaluators" ], "summary": "Per-day pass rate + mean score for an evaluator over a lookback window", "description": "Time-series of `(date, pass_rate, mean_score, sample_count)` for an evaluator.\n\nFilters EvalScore rows by `name=evaluator.name` joined to RunTrace for\norg-scoping. Used by the evaluator-detail drift chart per the audit#381\nproposal. The agent_name on the evaluator (if any) further narrows the\njoin — org-wide evaluators (agent_name=null) aggregate across all agents.", "operationId": "get_evaluator_pass_rate_trend_api_v1_evaluators__evaluator_id__pass_rate_trend_get", "parameters": [ { "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluator Id" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Evaluator Pass Rate Trend Api V1 Evaluators Evaluator Id Pass Rate Trend Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/staleness": { "get": { "tags": [ "evaluators" ], "summary": "Get staleness status for all evaluators of an agent", "description": "Get staleness status for all evaluators of an agent.\n\nReturns evaluators grouped into stale and fresh, with reasons.", "operationId": "get_eval_staleness_api_v1_evaluators_staleness_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Agent to check staleness for", "title": "Agent Name" }, "description": "Agent to check staleness for" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Eval Staleness Api V1 Evaluators Staleness Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/scan-staleness": { "post": { "tags": [ "evaluators" ], "summary": "Trigger a staleness scan for one agent or all agents in the org", "description": "Trigger a staleness scan for one agent or all agents in the org.", "operationId": "run_staleness_scan_api_v1_evaluators_scan_staleness_post", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent to scan (all if omitted)", "title": "Agent Name" }, "description": "Agent to scan (all if omitted)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Run Staleness Scan Api V1 Evaluators Scan Staleness Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evaluators/{evaluator_id}/mark-validated": { "post": { "tags": [ "evaluators" ], "summary": "Mark an evaluator as valid against the current manifest", "description": "Mark an evaluator as valid against the current manifest.\n\nUsed by the \"Mark still-valid\" action in the stale-case UI.\nClears staleness reasons and updates last_validated_manifest_id.", "operationId": "mark_evaluator_validated_api_v1_evaluators__evaluator_id__mark_validated_post", "parameters": [ { "name": "evaluator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluator Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Mark Evaluator Validated Api V1 Evaluators Evaluator Id Mark Validated Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evergreen/policies": { "post": { "tags": [ "evergreen" ], "summary": "Create an evergreen policy in one of the caller's projects", "description": "Create an evergreen policy (bound to a project the caller owns).", "operationId": "create_policy_api_v1_evergreen_policies_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "evergreen" ], "summary": "List the caller's org's evergreen policies", "description": "List the caller's org's evergreen policies.", "operationId": "list_policies_api_v1_evergreen_policies_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evergreen/tasks": { "post": { "tags": [ "evergreen" ], "summary": "Mark a trace as an evergreen task for continuous regression testing", "description": "Mark a trace as an evergreen task for continuous regression testing.", "operationId": "tag_evergreen_task_api_v1_evergreen_tasks_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "evergreen" ], "summary": "List evergreen tasks, optionally filtered by policy", "description": "List the caller's org's evergreen tasks, optionally filtered by policy.", "operationId": "list_evergreen_tasks_api_v1_evergreen_tasks_get", "parameters": [ { "name": "policy_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evergreen/reports": { "get": { "tags": [ "evergreen" ], "summary": "Get regression reports showing score trends across manifest versions", "description": "Get regression reports showing score trends across manifest versions.", "operationId": "get_regression_reports_api_v1_evergreen_reports_get", "parameters": [ { "name": "policy_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/import/jsonl": { "post": { "tags": [ "import" ], "summary": "Import traces from a JSONL upload (deprecated path — use /traces/import)", "description": "Upload and parse a JSONL file.\n\nSupports two formats:\n1. Chat messages: {\"messages\": [{\"role\": \"...\", \"content\": \"...\"}]}\n2. Instruction pairs: {\"input\": \"...\", \"output\": \"...\"}\n\nEach line becomes a trace with source_type=\"manual\".", "operationId": "import_jsonl_api_v1_import_jsonl_post", "deprecated": true, "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_import_jsonl_api_v1_import_jsonl_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Import Jsonl Api V1 Import Jsonl Post" }, "example": { "status": "ok", "imported_count": 100, "error_count": 2, "errors": [ "line 45: missing agent_name", "line 78: invalid span_type" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Bash", "label": "CLI", "source": "decimalai traces import traces.jsonl --format jsonl" } ] } }, "/api/v1/import/traces": { "post": { "tags": [ "import" ], "summary": "Bulk-import historical traces (deprecated path — use /traces/import-bulk)", "description": "Bulk-import historical traces — useful for migrating from another\nobservability tool or seeding the dashboard from a backup.\n\nBody: `{\"traces\": [...trace payloads...], \"source_type\": \"manual\"}`. Each\ntrace follows the same shape as POST /api/v1/traces. Duplicate `trace_id`\nvalues are silently skipped — re-running an import is safe.\n\n**Quota:** Imported traces count toward your plan's `traces_ingested`\nquota at half the rate of live ingest.", "operationId": "import_traces_api_v1_import_traces_post", "deprecated": true, "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Import Traces Api V1 Import Traces Post" }, "example": { "status": "ok", "imported_count": 10, "skipped_duplicates": 2, "error_count": 0, "errors": [] } } } }, "400": { "description": "Empty `traces` array." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx, json\n\nwith open(\"legacy_traces.jsonl\") as f:\n traces = [json.loads(line) for line in f]\n\n# Batch in 500-trace chunks to stay under request size limits\nfor i in range(0, len(traces), 500):\n chunk = traces[i:i + 500]\n resp = httpx.post(\n \"https://api.decimal.ai/api/v1/import/traces\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n json={\"traces\": chunk},\n timeout=60.0,\n )\n resp.raise_for_status()" }, { "lang": "Bash", "label": "CLI", "source": "decimalai traces import traces.jsonl" } ] } }, "/api/v1/import/langsmith": { "post": { "tags": [ "import" ], "summary": "Import a list of LangSmith Run objects (verbatim export format)", "description": "Accept a bare list of LangSmith `Run` exports — no wrapping required.\n\nCloses discovery/cuj04-langsmith-migrant-engineer/import-langsmith-shape-mismatch\n(filed at improve#607, consumed improve#608). Pre-fix the migration\nengine existed at `/api/v1/import/traces` but two friction points\nblocked the migrant's first attempt: (a) it expected `{\"traces\": [...]}`\nwrapping, not a bare list; (b) field names differed\n(`inputs/outputs/start_time` vs `input/output/start_time_ms`). This\nendpoint accepts LangSmith's verbatim Run shape and maps fields\ninternally, then delegates to the same baseline_cache path as\n`/import/traces` (auto-registers a baseline manifest per agent so\nthe migrant doesn't have to model DecimalAI's manifest concept).", "operationId": "import_langsmith_api_v1_import_langsmith_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Runs" } } } }, "responses": { "200": { "description": "Mapped + imported successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Import Langsmith Api V1 Import Langsmith Post" } } } }, "400": { "description": "Empty body or non-list payload" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/import": { "post": { "tags": [ "import" ], "summary": "Import traces from a JSONL upload", "description": "Upload and parse a JSONL file.\n\nSupports two formats:\n1. Chat messages: {\"messages\": [{\"role\": \"...\", \"content\": \"...\"}]}\n2. Instruction pairs: {\"input\": \"...\", \"output\": \"...\"}\n\nEach line becomes a trace with source_type=\"manual\".", "operationId": "import_jsonl_api_v1_traces_import_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_import_jsonl_api_v1_traces_import_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Import Jsonl Api V1 Traces Import Post" }, "example": { "status": "ok", "imported_count": 100, "error_count": 2, "errors": [ "line 45: missing agent_name", "line 78: invalid span_type" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Bash", "label": "CLI", "source": "decimalai traces import traces.jsonl --format jsonl" } ] } }, "/api/v1/traces/import-bulk": { "post": { "tags": [ "import" ], "summary": "Bulk-import historical traces", "description": "Bulk-import historical traces — useful for migrating from another\nobservability tool or seeding the dashboard from a backup.\n\nBody: `{\"traces\": [...trace payloads...], \"source_type\": \"manual\"}`. Each\ntrace follows the same shape as POST /api/v1/traces. Duplicate `trace_id`\nvalues are silently skipped — re-running an import is safe.\n\n**Quota:** Imported traces count toward your plan's `traces_ingested`\nquota at half the rate of live ingest.", "operationId": "import_traces_api_v1_traces_import_bulk_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Import Traces Api V1 Traces Import Bulk Post" }, "example": { "status": "ok", "imported_count": 10, "skipped_duplicates": 2, "error_count": 0, "errors": [] } } } }, "400": { "description": "Empty `traces` array." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests": { "post": { "tags": [ "manifests" ], "summary": "Register a manifest", "description": "Register a new manifest version.\n\nPayload should include:\n- manifest_hash (required)\n- agent_name\n- version_label\n- components: [{component_type, component_name, content_hash, schema_json, ...}]\n\nSupports `X-Idempotency-Key` for safe retries — within 60s, a request with\nthe same key returns the original response instead of registering twice.", "operationId": "register_manifest_api_v1_manifests_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Idempotency-Key" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "manifest_id": "mfst_abc123", "manifest_hash": "a1b2c3d4e5f60718", "version_label": "v2.1", "is_new": true, "components": 4, "compatibility_report_id": "compat_def456" } } } }, "400": { "description": "`manifest_hash` is required." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "# Recommended: framework-specific install() auto-captures the manifest at init.\nimport decimalai\nfrom decimalai.openai_agents import install\nfrom agents import Agent\n\ndecimalai.init(api_key=\"dai_sk_...\")\nagent = Agent(name=\"my-agent\", instructions=\"...\", tools=[...])\ninstall(agent=agent) # registers the manifest on first trace\n\n# Or call register_manifest directly for explicit control:\ndecimalai.register_manifest(\n api_key=\"dai_sk_...\",\n agent_name=\"my-agent\",\n version_label=\"v2.1\",\n components=[...],\n)" } ] }, "get": { "tags": [ "manifests" ], "summary": "List manifests", "description": "List manifests in timeline order.", "operationId": "list_manifests_api_v1_manifests_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "manifests": [ { "id": "mfst_001", "project_id": "proj_main", "version_label": "v2.1", "manifest_hash": "a1b2c3d4e5f60718", "parent_manifest_id": "mfst_000", "status": "active", "detection_source": "sdk", "agent_name": "travel-planner", "component_summary_json": { "tools": 4, "prompts": 2, "models": 1 }, "components_count": 7, "created_at": "2026-05-10T12:00:00Z" } ], "total": 5, "limit": 20, "offset": 0 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/manifests\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n params={\"agent_name\": \"my-agent\"},\n)\nresp.raise_for_status()\nfor m in resp.json()[\"manifests\"]:\n print(m[\"version_label\"], m[\"manifest_hash\"][:8])" }, { "lang": "Bash", "label": "CLI", "source": "decimalai manifests list --agent-name my-agent" } ] } }, "/api/v1/manifests/{manifest_id}": { "get": { "tags": [ "manifests" ], "summary": "Get a manifest", "description": "Get a manifest by ID with full component list.", "operationId": "get_manifest_api_v1_manifests__manifest_id__get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "mfst_abc123", "project_id": "proj_main", "version_label": "v2.1", "manifest_hash": "a1b2c3d4e5f60718", "parent_manifest_id": "mfst_000", "status": "active", "detection_source": "sdk", "agent_name": "travel-planner", "agent_models_json": { "primary": "gpt-4o" }, "graph_topology_hash": "topo_001", "component_summary_json": { "tools": 4, "prompts": 2 }, "created_at": "2026-05-10T12:00:00Z", "components": [ { "id": "comp_001", "component_type": "tool", "component_name": "search_flights", "component_version": "v1", "content_hash": "tool_hash_abc", "schema_json": { "parameters": { "type": "object" } } } ] } } } }, "404": { "description": "Manifest not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/manifests/mfst_abc123\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nmanifest = resp.json()" } ] } }, "/api/v1/manifests/{manifest_id}/diff": { "get": { "tags": [ "manifests" ], "summary": "Compute a diff between this manifest and another (or its parent)", "description": "Compute a diff between this manifest and another (or its parent).", "operationId": "diff_manifest_api_v1_manifests__manifest_id__diff_get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "compare_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Manifest ID to compare against (defaults to parent)", "title": "Compare To" }, "description": "Manifest ID to compare against (defaults to parent)" }, { "name": "against", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias for `compare_to` (H1100 — both names supported so callers don't have to guess).", "title": "Against" }, "description": "Alias for `compare_to` (H1100 — both names supported so callers don't have to guess)." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/suggested-evaluators": { "get": { "tags": [ "manifests" ], "summary": "Suggest evaluators based on what this manifest declares", "description": "B.1 — derive evaluator suggestions from the manifest's declared contract.\n\nComplementary to ``GET /api/v1/evaluators/suggestions`` (which is\ntrace-pattern-based). Both endpoints return the same shape so the\nfrontend can render them side-by-side.\n\nReturns 404 if the manifest doesn't exist in the caller's org.", "operationId": "suggested_evaluators_for_manifest_api_v1_manifests__manifest_id__suggested_evaluators_get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Suggested Evaluators For Manifest Api V1 Manifests Manifest Id Suggested Evaluators Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/compatibility": { "get": { "tags": [ "manifests" ], "summary": "Get compatibility reports for a manifest", "description": "Get compatibility reports for a manifest.", "operationId": "get_compatibility_api_v1_manifests__manifest_id__compatibility_get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/compatibility/episodes": { "get": { "tags": [ "manifests" ], "summary": "Drill down into per-episode compatibility verdicts", "description": "Drill down into per-episode compatibility verdicts.\n\nReturns individual episode verdicts from the stored compatibility report.\nOptionally filter by verdict (keep/repair/replay/drop).", "operationId": "get_compatibility_episodes_api_v1_manifests__manifest_id__compatibility_episodes_get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verdict" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/compatibility/run": { "post": { "tags": [ "manifests" ], "summary": "Run a fresh per-episode compatibility analysis", "description": "Run a fresh per-episode compatibility analysis.\n\nBody: {\"old_manifest_id\": \"...\"}", "operationId": "run_compatibility_analysis_api_v1_manifests__manifest_id__compatibility_run_post", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/timeline/{agent_name}.csv": { "get": { "tags": [ "manifests" ], "summary": "Export an agent's manifest timeline as CSV", "operationId": "export_manifest_timeline_csv_api_v1_manifests_timeline__agent_name__csv_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 200, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/timeline/{agent_name}": { "get": { "tags": [ "manifests" ], "summary": "Manifest timeline for an agent", "description": "Get the manifest timeline for an agent.\n\nReturns manifests in reverse-chronological order, each annotated with:\n- trace_count, dataset_count, dataset_row_count\n- diff_severity (max severity of diff vs parent)", "operationId": "get_manifest_timeline_api_v1_manifests_timeline__agent_name__get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/datasets": { "get": { "tags": [ "manifests" ], "summary": "Datasets linked to a manifest", "description": "Get datasets and their versions linked to a specific manifest.", "operationId": "get_manifest_datasets_api_v1_manifests__manifest_id__datasets_get", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/policies/presets": { "get": { "tags": [ "manifests" ], "summary": "Get policy presets", "description": "Get available policy presets (strict / default / permissive).", "operationId": "get_policy_presets_api_v1_manifests_policies_presets_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/policies": { "post": { "tags": [ "manifests" ], "summary": "Create a new compatibility policy", "description": "Create a new compatibility policy.\n\nBody: {\n \"project_id\": \"...\",\n \"agent_name\": \"...\", // optional — null = project-level default\n \"name\": \"my-policy\",\n \"preset\": \"default\", // strict / default / permissive / custom\n \"rules_json\": {...} // optional — overrides preset\n}", "operationId": "create_policy_api_v1_manifests_policies_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/policies/active": { "get": { "tags": [ "manifests" ], "summary": "Get the active policy for an agent or project", "description": "Get the active policy for an agent or project.", "operationId": "get_active_policy_api_v1_manifests_policies_active_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/policies/{policy_id}": { "put": { "tags": [ "manifests" ], "summary": "Update a policy's rules or preset.\"\"\"", "description": "Update a policy's rules or preset.", "operationId": "update_policy_api_v1_manifests_policies__policy_id__put", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/apply-policy": { "post": { "tags": [ "manifests" ], "summary": "Apply a compatibility policy to a manifest diff", "description": "Apply a compatibility policy to a manifest diff.\n\nBody: {\n \"policy_id\": \"...\" or \"preset\": \"strict\",\n \"compare_to\": \"...\" // optional — defaults to parent\n}", "operationId": "apply_policy_to_manifest_api_v1_manifests__manifest_id__apply_policy_post", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/impact-preview": { "post": { "tags": [ "manifests", "policies" ], "summary": "Preview the impact of a policy on traces", "description": "Preview how many traces would be affected by each action bucket.\n\nUses per-episode classification: each trace is scored based on which\ncomponents it actually used, not just the manifest-level diff.\n\nBody: {\n \"policy_id\": \"...\" or \"preset\": \"strict\",\n \"compare_to\": \"...\" // optional\n}", "operationId": "impact_preview_api_v1_manifests__manifest_id__impact_preview_post", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/manifests/{manifest_id}/rollback": { "post": { "tags": [ "manifests" ], "summary": "Roll back to a prior manifest — one-click oncall mitigation", "description": "One-click rollback to a prior manifest version.\n\nCloses discovery/cuj17_oncall_paged_3am/no-manifest-rollback-endpoint\n(filed at improve#609, consumed improve#610). Pre-fix oncall users\nhad to (1) look up the previous manifest_id, (2) re-register with\nthat hash, (3) hope the auto-revert path inside `register_manifest`\ncatches it. That's 3-step cognitive work at 3am. Now: one POST.\n\nFlow:\n 1. Load the target manifest. Org-scoped (404 if not in caller's org).\n 2. If target is already `status=active`, return 400.\n 3. Find the current active manifest for the same agent.\n 4. Atomically: mark current_active = 'superseded', target = 'active'.\n 5. Write an AuditLog row with action='manifest.rollback', target_id=\n the manifest being deactivated, metadata=which manifest is now active.\n 6. Return the now-active manifest.\n\nOptional body: `{\"reason\": \"...\"}` is recorded in audit_log.metadata_json.", "operationId": "rollback_manifest_api_v1_manifests__manifest_id__rollback_post", "parameters": [ { "name": "manifest_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Manifest Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "description": "Rolled back successfully", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Manifest already active or invalid rollback target" }, "404": { "description": "Manifest not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org": { "get": { "tags": [ "organization" ], "summary": "Get current organization details", "description": "Get current organization details.", "operationId": "get_org_api_v1_org_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Org Api V1 Org Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/members": { "get": { "tags": [ "organization" ], "summary": "List all org members", "description": "List all org members.", "operationId": "list_members_api_v1_org_members_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Members Api V1 Org Members Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/invitations": { "post": { "tags": [ "organization" ], "summary": "Invite a new member to the org (canonical REST plural; improve#634)", "description": "Invite a new member to the org.\n\nBody: {\"email\": \"...\", \"role\": \"member\", \"workspace_id\": \"...\"}", "operationId": "invite_member_api_v1_org_invitations_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Invite Member Api V1 Org Invitations Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "organization" ], "summary": "List pending invitations for the org (improve#634)", "description": "List invitations for the caller's org.\n\nCloses part of discovery/cuj24-hr-add-member/invitations-path-mismatch\n(proposed improve#633, consumed improve#634). HR wants to see who's\nbeen invited — previously the only listing was via the dashboard UI.\n\nOrg-scoped via the auth context. Optional `?status=pending|accepted|expired`\nfilter. Token is NOT returned in the list (only on create).", "operationId": "list_invitations_api_v1_org_invitations_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Invitations Api V1 Org Invitations Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/invite": { "post": { "tags": [ "organization" ], "summary": "Invite a new member to the org", "description": "Invite a new member to the org.\n\nBody: {\"email\": \"...\", \"role\": \"member\", \"workspace_id\": \"...\"}", "operationId": "invite_member_api_v1_org_invite_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Invite Member Api V1 Org Invite Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/invitations/bulk": { "post": { "tags": [ "organization" ], "summary": "Bulk-invite up to 100 members in one call (improve#635)", "description": "Bulk-invite multiple members in one call.\n\nBody: `{\"invites\": [{\"email\": \"...\", \"role\": \"editor\", \"workspace_id\": \"...\"}, ...]}`\nReturns `{succeeded_count, failed_count, succeeded: [...], failed: [{index, email, error}, ...]}`.\n\nA failure on one invite does NOT abort the batch — remaining invites\nstill process (per-row not whole-batch atomicity). Max 100 per call.\n\nCloses discovery/cuj24-hr-add-member/no-bulk-invite-endpoint\n(proposed improve#633, consumed improve#635). Realistic HR workflow:\nCSV import of new hires → one POST creates all invitations.", "operationId": "bulk_invite_members_api_v1_org_invitations_bulk_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Bulk Invite Members Api V1 Org Invitations Bulk Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/accept-invite": { "post": { "tags": [ "organization" ], "summary": "Accept an invitation", "description": "Accept an invitation.\n\nBody: {\"token\": \"...\"}", "operationId": "accept_invite_api_v1_org_accept_invite_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Body" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Accept Invite Api V1 Org Accept Invite Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/members/{user_id}": { "delete": { "tags": [ "organization" ], "summary": "Remove a member from the org", "description": "Remove a member from the org.", "operationId": "remove_member_api_v1_org_members__user_id__delete", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Remove Member Api V1 Org Members User Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/org/notifications": { "get": { "tags": [ "organization" ], "summary": "Get notification settings for the org", "description": "Get notification settings for the org.", "operationId": "get_notification_settings_api_v1_org_notifications_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Notification Settings Api V1 Org Notifications Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "organization" ], "summary": "Update notification settings for the org", "description": "Update notification settings for the org.\n\nBody: {\"webhook_url\": \"https://...\", \"events\": [\"manifest.changed\", ...]}", "operationId": "update_notification_settings_api_v1_org_notifications_patch", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Notification Settings Api V1 Org Notifications Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/playground/traces": { "get": { "tags": [ "playground" ], "summary": "Get recent traces with LLM call messages for playground testing", "description": "Get recent traces with LLM call messages for playground testing.\n\nReturns traces with their rendered_input_json so the frontend can\npopulate the playground with real messages.", "operationId": "get_playground_traces_api_v1_playground_traces_get", "parameters": [ { "name": "skill_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by skill activation", "title": "Skill Name" }, "description": "Filter by skill activation" }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by agent", "title": "Agent Name" }, "description": "Filter by agent" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/playground/run": { "post": { "tags": [ "playground" ], "summary": "Execute a modified LLM call using the user's stored credentials", "description": "Execute a modified LLM call using the user's stored credentials.\n\nBYOK model: the user must have configured their API key in Settings.\nThe platform does NOT subsidize LLM calls for playground use.", "operationId": "run_playground_api_v1_playground_run_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundRunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/playground/compare": { "post": { "tags": [ "playground" ], "summary": "Opt-in pairwise preference verdict (runs on the user's BYOK key)", "description": "Relative pairwise preference of ``candidate`` vs ``baseline`` for the same input.\n\nA *model opinion* (temp 0), not an absolute score. Opt-in (the UI never fires\nit automatically) and judged on the user's **own provider key** — the same\nBYOK key used for the completions — so it never touches a platform key. Verdict\n∈ {preferred, tie, worse} is the candidate relative to the baseline.", "operationId": "compare_playground_api_v1_playground_compare_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundCompareRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/projects": { "post": { "tags": [ "projects" ], "summary": "Create a new project in the caller's org", "description": "Create a new project in the caller's org.", "operationId": "create_project_api_v1_projects_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "projects" ], "summary": "List the caller's org's projects", "description": "List the caller's org's projects.", "operationId": "list_projects_api_v1_projects_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/projects/{project_id}": { "get": { "tags": [ "projects" ], "summary": "Get a project by ID", "description": "Get a project by ID (caller's org only).", "operationId": "get_project_api_v1_projects__project_id__get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "projects" ], "summary": "Update a project", "description": "Update a project (caller's org only).", "operationId": "update_project_api_v1_projects__project_id__put", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-check": { "post": { "tags": [ "regression" ], "summary": "Run a regression check for a candidate manifest against the baseline", "description": "Run a regression check for a candidate manifest against the baseline.\n\nRequest body:\n {\n \"agent_name\": \"support-agent\",\n \"candidate_manifest_id\": \"mfst_xyz\",\n \"pr_context\": { # optional\n \"repo\": \"acme/support-bot\",\n \"pr_number\": 42,\n \"branch\": \"fix/refund-prompt\",\n \"commit_sha\": \"abc123\"\n },\n \"trace_window_days\": 30 # optional, default 30\n }\n\nQuery params:\n dry_run=true: compute the impact report but do NOT persist a\n RegressionCheck row and do NOT consume the org's metered quota.\n Useful for local exploration. The response has no `id` field\n and the `pr_context` is ignored.\n\nResponse: see ImpactReport structure in manifest_impact_service.py.\n\nBehavior on edge cases:\n - No baseline exists → returns verdict='first_run', registers candidate\n as baseline, status='completed' with zero impacts. (Decision #11)\n (Dry-run mode does not register the candidate as baseline either.)\n - Candidate manifest doesn't exist → 404\n - Candidate manifest belongs to a different agent → 400", "operationId": "create_regression_check_api_v1_regression_check_post", "parameters": [ { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Compute the report without persisting or metering.", "default": false, "title": "Dry Run" }, "description": "Compute the report without persisting or metering." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "regression" ], "summary": "List regression checks for an agent, most recent first", "description": "List regression checks for an agent, most recent first.", "operationId": "list_regression_checks_api_v1_regression_check_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-check/{regression_check_id}": { "get": { "tags": [ "regression" ], "summary": "Fetch a regression check by ID. Used by the frontend detail page", "description": "Fetch a regression check by ID. Used by the frontend detail page.", "operationId": "get_regression_check_api_v1_regression_check__regression_check_id__get", "parameters": [ { "name": "regression_check_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Regression Check Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-check/{regression_check_id}/decision": { "post": { "tags": [ "regression" ], "summary": "Set the engineer's human_decision on a regression check", "description": "Annotate a regression check with the engineer's decision.\n\nRequest body:\n {\"decision\": \"intentional\" | \"acknowledged\" | \"needs_review\" | null}\n\nSetting decision to null clears any prior decision. The auto-computed\nstructural + eval verdicts are unchanged — this is purely a human\nannotation layer on top.", "operationId": "set_regression_check_decision_api_v1_regression_check__regression_check_id__decision_post", "parameters": [ { "name": "regression_check_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Regression Check Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionPayload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-check/{regression_check_id}/call-replay": { "post": { "tags": [ "regression" ], "summary": "Behavioral call-replay for a check's model change (defaults to mock — no token spend)", "description": "Re-issue a representative recorded model call per affected trace against\nthe candidate model and diff vs the recorded answer.\n\n``mode=mock`` (default) never spends tokens — safe for a dashboard click.\n``mode=real`` performs live same-provider calls with the server's key\n(opt-in; costs tokens). Same-provider MVP (OpenAI/Gemini).", "operationId": "run_regression_check_call_replay_api_v1_regression_check__regression_check_id__call_replay_post", "parameters": [ { "name": "regression_check_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Regression Check Id" } }, { "name": "mode", "in": "query", "required": false, "schema": { "enum": [ "mock", "real" ], "type": "string", "description": "mock (default, no spend) returns deterministic outputs; real performs live same-provider calls with the server key.", "default": "mock", "title": "Mode" }, "description": "mock (default, no spend) returns deterministic outputs; real performs live same-provider calls with the server key." }, { "name": "per_trace", "in": "query", "required": false, "schema": { "enum": [ "first", "all" ], "type": "string", "description": "Which recorded call(s) per affected trace to replay. first = the representative (earliest) call; all is reserved.", "default": "first", "title": "Per Trace" }, "description": "Which recorded call(s) per affected trace to replay. first = the representative (earliest) call; all is reserved." }, { "name": "judge", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also run the LLM-judge tier on changed samples (better/worse/equivalent vs the recorded answer). In real mode this spends a judge call per changed sample.", "default": false, "title": "Judge" }, "description": "Also run the LLM-judge tier on changed samples (better/worse/equivalent vs the recorded answer). In real mode this spends a judge call per changed sample." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/regression-timeline": { "get": { "tags": [ "regression" ], "summary": "Get Regression Timeline", "description": "Return the per-manifest metric time series + regression detection.\n\nUsed by the bisect view on the agent dashboard to identify which\nmanifest version introduced a regression. See CUJ 13 spec for the\ndetection rules.", "operationId": "get_regression_timeline_api_v1_agents__agent_name__regression_timeline_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "eval_pass_rate", "title": "Metric" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 7, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_name}/ci-setup-status": { "get": { "tags": [ "regression" ], "summary": "Get Ci Setup Status", "description": "Return whether CI for regression checks is wired up for this agent.\n\nResponse shape:\n {\n \"has_run_count\": int, # total regression checks ever for this agent\n \"last_run_at\": ISO8601 | null, # created_at of the most recent check, if any\n \"status\": \"never_run\" | \"recent\" | \"stale\",\n }\n\nStatus semantics:\n - never_run: no regression check has ever run for this agent\n - recent: at least one check ran in the last 7 days\n - stale: the most recent check is older than 7 days", "operationId": "get_ci_setup_status_api_v1_agents__agent_name__ci_setup_status_get", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts": { "post": { "tags": [ "regression" ], "summary": "Create Regression Alert", "description": "Manually flag a manifest as regressed.\n\nBody:\n {\n \"agent_name\": \"support-agent\",\n \"manifest_id\": \"mfst_v25\",\n \"metric\": \"eval_pass_rate\", # optional, defaults to eval_pass_rate\n \"reason\": \"noticed pass rate dropped\" # optional free-text\n }\n\nIdempotent: if an alert already exists for (org, agent, manifest, metric),\nthat existing alert is returned with status code 200. If a new alert is\ncreated, the configured webhook fires.\n\nWrites an AuditLog row (action=regression_alert.create) for traceability —\nsee D4. Failure to write the audit row never blocks alert creation.", "operationId": "create_regression_alert_api_v1_regression_alerts_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "regression" ], "summary": "List Regression Alerts", "description": "List alerts for an agent, optionally filtered by status.", "operationId": "list_regression_alerts_api_v1_regression_alerts_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601; only alerts created at-or-after this time.", "title": "Since" }, "description": "ISO-8601; only alerts created at-or-after this time." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/stats": { "get": { "tags": [ "regression" ], "summary": "Aggregate regression-alert stats: counts, MTTR, by-agent / by-severity", "description": "Closes discovery/cuj13_pm_alert_audit/no-alerts-aggregate-endpoint (filed improve#630, consumed improve#631). PM can audit alerts with one HTTP call instead of paginating + aggregating client-side.", "operationId": "get_regression_alerts_stats_api_v1_regression_alerts_stats_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 timestamp; only alerts created at-or-after this point are counted.", "title": "Since" }, "description": "ISO-8601 timestamp; only alerts created at-or-after this point are counted." }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single agent.", "title": "Agent Name" }, "description": "Filter to a single agent." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/active-by-agent": { "get": { "tags": [ "regression" ], "summary": "Active alerts grouped by agent — for the on-call landing surface", "description": "Closes part of discovery/cuj17_oncall_paged_3am/no-incidents-landing-surface (filed improve#537, consumed improve#636). On-call SRE paged at 3 AM needs a one-call answer to 'which agents need attention right now?' without paginating through `/regression-alerts` per-agent. Returns agents with at least one open (active OR acknowledged) alert, sorted by most-recent alert first.", "operationId": "get_active_alerts_by_agent_api_v1_regression_alerts_active_by_agent_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max agents to return.", "default": 20, "title": "Limit" }, "description": "Max agents to return." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/{alert_id}": { "get": { "tags": [ "regression" ], "summary": "Get Regression Alert", "description": "Fetch a single alert by ID.", "operationId": "get_regression_alert_api_v1_regression_alerts__alert_id__get", "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Alert Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/{alert_id}/acknowledge": { "post": { "tags": [ "regression" ], "summary": "Acknowledge Regression Alert", "description": "Mark an alert as acknowledged (engineer saw it but hasn't fixed yet).", "operationId": "acknowledge_regression_alert_api_v1_regression_alerts__alert_id__acknowledge_post", "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Alert Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/{alert_id}/resolve": { "post": { "tags": [ "regression" ], "summary": "Resolve Regression Alert", "description": "Mark an alert as resolved (regression no longer applies).", "operationId": "resolve_regression_alert_api_v1_regression_alerts__alert_id__resolve_post", "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Alert Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/regression-alerts/{alert_id}/rollback-preview": { "get": { "tags": [ "regression" ], "summary": "Get Rollback Preview", "description": "Generate a rollback preview for an alert.\n\nReturns a structured list of \"things to revert\" — the engineer's checklist\nfor manually rolling back the regressing manifest to its baseline.\n\nDecimalAI does not auto-deploy rollbacks; this is purely advisory.", "operationId": "get_rollback_preview_api_v1_regression_alerts__alert_id__rollback_preview_get", "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Alert Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/repair/preview": { "post": { "tags": [ "repair" ], "summary": "Preview repairs for a manifest transition", "description": "Preview repairs for a manifest transition.", "operationId": "preview_repairs_api_v1_repair_preview_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRepairRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/repair/apply": { "post": { "tags": [ "repair" ], "summary": "Apply repairs to all eligible episodes", "description": "Apply repairs to all eligible episodes.", "operationId": "apply_repairs_api_v1_repair_apply_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyRepairRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/repair/{batch_id}": { "get": { "tags": [ "repair" ], "summary": "Get repair batch status and results", "description": "Get repair batch status and results.", "operationId": "get_repair_batch_api_v1_repair__batch_id__get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/repair/apply-selective": { "post": { "tags": [ "repair" ], "summary": "Apply only user-approved repair rules", "description": "Apply only user-approved repair rules.", "operationId": "apply_repairs_selective_api_v1_repair_apply_selective_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplySelectiveRepairRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/replay/batches": { "post": { "tags": [ "replay" ], "summary": "Create a replay batch", "description": "Create a replay batch.\n\nRequires `trace_ids` and `target_manifest_id`. The batch enqueues one task\nper trace; submit results back via `POST /api/v1/replay/tasks/{task_id}/submit`.", "operationId": "create_batch_api_v1_replay_batches_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "batch_id": "rb_abc123", "total_tasks": 50, "batch_status": "pending" } } } }, "400": { "description": "`trace_ids` and `target_manifest_id` are required." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\ndecimalai.init(api_key=\"dai_sk_...\")\n\nbatch = decimalai.create_replay_batch(\n agent_name=\"my-agent\",\n target_manifest_id=\"mfst_new\",\n trace_ids=[\"trc_001\", \"trc_002\"],\n)" } ] }, "get": { "tags": [ "replay" ], "summary": "List replay batches", "description": "List replay batches in the workspace, newest first.\n\nEach row is enriched with `agent_name` (denormalized from the batch's\ntarget manifest, or source manifest when target is absent) so the\nworkspace-wide `/replay` page can render `\"agent-x: 12 of 18 passed\"`\nwithout an extra round-trip per row.\n\nPagination: `limit` (1-100, default 20) and `offset` (default 0).\nResponse: `{batches: [...], total, limit, offset}`.", "operationId": "list_batches_api_v1_replay_batches_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/replay/batches/{batch_id}": { "get": { "tags": [ "replay" ], "summary": "Get a replay batch", "description": "Get a replay batch with full task breakdown.\n\nReturns the batch's status, task counts, and the per-task list with\neach task's `original_trace_id`, `replayed_trace_id`, `eval_score`,\n`eval_verdict`, and `task_input`. 404 if the batch isn't visible to\nthe authenticated workspace.", "operationId": "get_batch_api_v1_replay_batches__batch_id__get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "rb_abc123", "status": "running", "total_tasks": 50, "completed_tasks": 48, "passed_tasks": 45, "failed_tasks": 3, "tasks": [ { "id": "rt_001", "original_trace_id": "trc_001", "replayed_trace_id": "trc_new_001", "status": "passed", "eval_score": 0.94, "eval_verdict": "keep", "task_input": { "input": "What flights go to Tokyo?" } } ] } } } }, "404": { "description": "Batch not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\ndecimalai.init(api_key=\"dai_sk_...\")\n\nbatch = decimalai.get_replay_batch(\"rb_abc123\")" } ] } }, "/api/v1/replay/tasks/{task_id}": { "get": { "tags": [ "replay" ], "summary": "Get a single replay task with its input for execution", "description": "Get a single replay task with its input for execution.", "operationId": "get_task_api_v1_replay_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/replay/tasks/{task_id}/submit": { "post": { "tags": [ "replay" ], "summary": "Submit a replay task result", "description": "Submit the result of a replay task.", "operationId": "submit_result_api_v1_replay_tasks__task_id__submit_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "ok", "task_id": "rt_001", "eval_score": 0.94, "eval_verdict": "keep" } } } }, "404": { "description": "Replay task not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\ndecimalai.init(api_key=\"dai_sk_...\")\n\ndecimalai.submit_replay_result(\n task_id=\"rt_001\",\n replayed_trace_id=\"trc_new_001\",\n status=\"completed\",\n)" }, { "lang": "Bash", "label": "CLI", "source": "decimalai replay run rb_abc123 --agent-fn my_app.agent:run" } ] } }, "/api/v1/replay/export": { "get": { "tags": [ "replay" ], "summary": "Export replay prompts", "description": "Export traces needing replay as a downloadable file.\n\nReturns a list of prompts (user inputs) from traces that need to be\nre-run against the current agent version. Users download this file,\nrun the prompts against their agent externally, then submit the new\ntraces back to DecimalAI.\n\nEach row includes a ``replay_context`` object explaining *why* the\ntrace needs replay — what surfaces changed, which skills/tools were\ninvolved, and the compat reason. This metadata is informational and\ndoes not control agent behavior during replay.\n\nFilter by verdict to get specific subsets:\n- replay: traces that can't be mechanically repaired\n- drop: traces that are incompatible\n- repair: traces that need schema fixes", "operationId": "export_replay_prompts_api_v1_replay_export_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Agent to export replay prompts for", "title": "Agent Name" }, "description": "Agent to export replay prompts for" }, { "name": "verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by verdict: replay, drop, repair", "title": "Verdict" }, "description": "Filter by verdict: replay, drop, repair" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Export format: jsonl or json", "default": "jsonl", "title": "Format" }, "description": "Export format: jsonl or json" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "default": 500, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "prompts": [ { "trace_id": "trc_001", "input": "What flights go to Tokyo?", "manifest_id": "mfst_old", "verdict": "replay" } ], "total": 50, "limit": 10 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\ndecimalai.init(api_key=\"dai_sk_...\")\n\nprompts = decimalai.get_replay_prompts(agent_name=\"my-agent\", limit=10)" } ] } }, "/api/v1/replay/export/sessions": { "get": { "tags": [ "replay" ], "summary": "Export multi-turn sessions that need replay", "description": "Export multi-turn sessions that need replay.\n\nGroups replay-eligible traces by ``session_id`` and includes **all**\nturns in each session (including non-replay ones) in chronological\norder. This enables the SDK to replay the full conversation with\nhistory accumulation.\n\nStandalone traces (``session_id`` is null) are returned as\nsingle-turn sessions.\n\nEach session includes:\n- ``session_id``: The session group key\n- ``turns``: Ordered list of turns with ``turn_index``, ``trace_id``,\n ``user_input``, ``original_output``, and ``is_trigger``\n- ``verdict``: The worst verdict among trigger turns\n- ``agent_name``: The agent name\n\nA turn is a **trigger** if it has a replay-eligible verdict.\nNon-trigger turns provide context for the agent.", "operationId": "export_replay_sessions_api_v1_replay_export_sessions_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Agent to export replay sessions for", "title": "Agent Name" }, "description": "Agent to export replay sessions for" }, { "name": "verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter trigger turns by verdict", "title": "Verdict" }, "description": "Filter trigger turns by verdict" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Export format: json or jsonl", "default": "json", "title": "Format" }, "description": "Export format: json or jsonl" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Max sessions to return", "default": 50, "title": "Limit" }, "description": "Max sessions to return" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/replay/link": { "post": { "tags": [ "replay" ], "summary": "Link a replayed trace to its original", "description": "Link a replayed trace to its original.\n\nCreates a replay task connecting the two traces and auto-scores\nthe replayed trace against the original. No batch creation required.\n\nUsed by the SDK's ``replay.link()`` function for manual replay flows.", "operationId": "link_replay_traces_api_v1_replay_link_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/replay/batches/{batch_id}/export-dpo": { "get": { "tags": [ "replay" ], "summary": "Export DPO preference pairs from a completed replay batch", "description": "Export DPO preference pairs from a completed replay batch.\n\nFor each completed replay task, compares original vs replayed outputs\nand uses eval scores to determine which is preferred. Returns pairs in\nthe standard DPO training format: {prompt, chosen, rejected}.\n\nPairs where the score difference is below ``score_threshold`` are\nskipped as ambiguous.", "operationId": "export_dpo_pairs_api_v1_replay_batches__batch_id__export_dpo_get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Export format: jsonl or json", "default": "jsonl", "title": "Format" }, "description": "Export format: jsonl or json" }, { "name": "score_threshold", "in": "query", "required": false, "schema": { "type": "number", "maximum": 0.5, "minimum": 0, "description": "Min score difference for preference pair", "default": 0.1, "title": "Score Threshold" }, "description": "Min score difference for preference pair" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings": { "get": { "tags": [ "settings" ], "summary": "Get platform configuration and statistics", "description": "Get platform configuration and statistics.", "operationId": "get_settings_api_v1_settings_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings/api-keys": { "post": { "tags": [ "settings" ], "summary": "Create a new API key", "description": "Create a new API key.\n\nBody:\n- label (required): Human-readable name for the key\n- scope: \"global\" or \"project\" (default: \"global\")\n- project_id: Required when scope is \"project\"\n\nReturns the raw key ONCE — it cannot be retrieved again.\nOnly global-scoped keys can create other keys.", "operationId": "create_api_key_api_v1_settings_api_keys_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "settings" ], "summary": "List all API keys (prefix and label only — no raw keys)", "description": "List this org's API keys (prefix and label only — no raw keys).\n\nOnly global-scoped keys can list keys.", "operationId": "list_api_keys_api_v1_settings_api_keys_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings/api-keys/{key_id}": { "delete": { "tags": [ "settings" ], "summary": "Revoke an API key. Only global-scoped keys can revoke keys", "description": "Revoke an API key. Only global-scoped keys can revoke keys.", "operationId": "revoke_api_key_api_v1_settings_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/api-keys": { "post": { "tags": [ "api-keys" ], "summary": "Create a new API key (canonical REST path; improve#613)", "description": "Create a new API key.\n\nBody:\n- label (required): Human-readable name for the key\n- scope: \"global\" or \"project\" (default: \"global\")\n- project_id: Required when scope is \"project\"\n\nReturns the raw key ONCE — it cannot be retrieved again.\nOnly global-scoped keys can create other keys.", "operationId": "create_api_key_api_v1_api_keys_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "api-keys" ], "summary": "List all API keys (canonical REST path; improve#613)", "description": "List this org's API keys (prefix and label only — no raw keys).\n\nOnly global-scoped keys can list keys.", "operationId": "list_api_keys_api_v1_api_keys_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/api-keys/{key_id}": { "delete": { "tags": [ "api-keys" ], "summary": "Revoke an API key (canonical REST path; improve#613)", "description": "Revoke an API key. Only global-scoped keys can revoke keys.", "operationId": "revoke_api_key_api_v1_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/suggest-improvement": { "post": { "tags": [ "skills" ], "summary": "Generate an AI-powered improvement suggestion for a skill", "description": "Generate an AI-powered improvement suggestion for a skill.\n\nAnalyzes recent failing traces where this skill was active and\nproposes specific edits to the skill body markdown.\n\nBody (optional):\n agent_name: Filter failing traces to a specific agent\n max_traces: Max number of failing traces to analyze (default: 10)", "operationId": "suggest_improvement_api_v1_skills__skill_name__suggest_improvement_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "default": {}, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/apply-suggestion": { "post": { "tags": [ "skills" ], "summary": "Apply a suggested improvement by creating a new skill version", "description": "Apply a suggested improvement by creating a new skill version.\n\nBody:\n suggested_body: The improved skill body markdown to apply", "operationId": "apply_suggestion_api_v1_skills__skill_name__apply_suggestion_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/suggestions": { "get": { "tags": [ "skills" ], "summary": "List past AI-generated suggestion versions for a skill", "description": "List past AI-generated suggestion versions for a skill.", "operationId": "list_suggestions_api_v1_skills__skill_name__suggestions_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}/attachments": { "get": { "tags": [ "skill-attachments" ], "summary": "List all attachments for a skill", "description": "List all attachments for a skill.\n\nReturns metadata for each file (no content_text for efficiency).\nUse GET /attachments/{id} to fetch full content.", "operationId": "list_attachments_api_v1_skills__skill_id__attachments_get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "directory", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by directory", "title": "Directory" }, "description": "Filter by directory" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "skill-attachments" ], "summary": "Upload a single attachment to a skill", "description": "Upload a single attachment to a skill.\n\nRequires edit permission on the skill.", "operationId": "create_attachment_api_v1_skills__skill_id__attachments_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}/attachments/{attachment_id}": { "get": { "tags": [ "skill-attachments" ], "summary": "Get a single attachment with its full content", "description": "Get a single attachment with its full content.", "operationId": "get_attachment_api_v1_skills__skill_id__attachments__attachment_id__get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Attachment Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "skill-attachments" ], "summary": "Delete a single attachment", "description": "Delete a single attachment.\n\nRequires edit permission on the skill.", "operationId": "delete_attachment_api_v1_skills__skill_id__attachments__attachment_id__delete", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Attachment Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}/attachments/by-path/{file_path}": { "get": { "tags": [ "skill-attachments" ], "summary": "Get an attachment by its relative file path", "description": "Get an attachment by its relative file path.\n\nExample: GET /api/v1/skills/{id}/attachments/by-path/scripts/validate.py", "operationId": "get_attachment_by_path_api_v1_skills__skill_id__attachments_by_path__file_path__get", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "file_path", "in": "path", "required": true, "schema": { "type": "string", "title": "File Path" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "skill-attachments" ], "summary": "Overwrite an existing attachment by path (stable attachment_id)", "description": "Overwrite an attachment's content in place — keeps `attachment_id` stable.\n\nPre-fix the only way to change a script was DELETE + POST, which\nchanged the ID and broke SDK consumers that cached it. PUT-by-path\nis idempotent and preserves the ID.\n\nReturns 404 if no matching file_path exists on this skill.", "operationId": "update_attachment_api_v1_skills__skill_id__attachments_by_path__file_path__put", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "file_path", "in": "path", "required": true, "schema": { "type": "string", "title": "File Path" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAttachmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}/attachments/bulk": { "post": { "tags": [ "skill-attachments" ], "summary": "Upload multiple attachments at once", "description": "Upload multiple attachments at once.\n\nRequires edit permission on the skill.\nUsed by the import pipeline for full bundle imports.", "operationId": "bulk_create_attachments_api_v1_skills__skill_id__attachments_bulk_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateAttachmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills": { "post": { "tags": [ "skills" ], "summary": "Create a skill", "description": "Create a new skill with its first version.\n\nOwnership is set automatically:\n- `creator_user_id` from the authenticated user\n- `owning_workspace_id` from the payload or auth context\n\nName must be lowercase alphanumeric with hyphens/underscores (1-200 chars).\nVisibility must be one of: `org`, `workspace`, `personal`, `public`.\nStability must be one of: `stable`, `experimental`, `deprecated`.\n\nSupports `X-Idempotency-Key` for safe retries — within 60s, a request with\nthe same key returns the original response instead of creating a duplicate.", "operationId": "create_skill_api_v1_skills_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Idempotency-Key" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" }, "examples": { "minimal": { "summary": "Minimal — name, description, body", "value": { "name": "search-flights", "description": "Search available flights", "body_markdown": "# Search Flights\n\n## When to activate\nUse this when the user asks about flight availability." } }, "full": { "summary": "Full — with category, stability, trigger phrases", "value": { "name": "search-flights", "description": "Search available flights given origin, destination, and dates.", "body_markdown": "# Search Flights\n\n## When to activate\nUse this when the user asks about flight availability between two cities.\n\n## Process\n1. Parse origin, destination, and date range from the user's request.\n2. Call the flight search API.\n3. Rank results by price ascending, then by departure time.\n", "category": "tools", "stability": "stable", "trigger_phrases": [ "find flights", "search for flights" ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillResponse" }, "example": { "status": "ok", "skill_id": "sk_abc123", "name": "search-flights", "version": 1 } } } }, "409": { "description": "A skill with this name already exists in the org." }, "422": { "description": "Validation failed (invalid name, body too short, etc.)." } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nrouter.create_skill(\n name=\"search-flights\",\n description=\"Search available flights\",\n body_markdown=\"# Search Flights\\n\\n## When to activate\\nUse when the user asks about flight availability.\",\n)" } ] }, "get": { "tags": [ "skills" ], "summary": "List skills", "description": "List all skills for the organization.\n\nReturns enriched data including ownership info, agent associations,\nsubscriber counts, and a `can_edit` flag for the current caller.\nResults are filtered by visibility — only skills the caller can see.", "operationId": "list_skills_api_v1_skills_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category (e.g. 'tools', 'policies', 'workflows').", "examples": [ "tools" ], "title": "Category" }, "description": "Filter by category (e.g. 'tools', 'policies', 'workflows')." }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Exclude soft-deleted skills.", "default": true, "title": "Active Only" }, "description": "Exclude soft-deleted skills." }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single project.", "title": "Project Id" }, "description": "Filter to a single project." }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact-match filter on skill name — a 200/empty-list existence probe (the detail page uses it instead of a guaranteed-404 GET).", "title": "Name" }, "description": "Exact-match filter on skill name — a 200/empty-list existence probe (the detail page uses it instead of a guaranteed-404 GET)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Max results (1–500).", "default": 100, "title": "Limit" }, "description": "Max results (1–500)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset.", "default": 0, "title": "Offset" }, "description": "Pagination offset." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillsResponse" }, "example": { "skills": [ { "id": "sk_abc123", "name": "search-flights", "description": "Search available flights", "category": "tools", "stability": "stable", "is_active": true, "visibility": "org", "latest_version_id": "sv_def456", "latest_version": { "version_number": 3, "content_hash": "a1b2c3d4e5f60718", "change_summary": "Added retry logic on timeout", "author": "alice@example.com", "created_at": "2026-05-10T14:22:00Z" }, "embedding_model": "text-embedding-3-small", "trigger_phrases": [ "find flights" ], "activation_count": 142, "agents": [ { "agent_name": "travel-agent", "activation_count": 142 } ], "agent_count": 1, "owner": { "user_id": "user_123", "user_name": "Alice", "workspace_id": "ws_main", "workspace_name": "Main" }, "can_edit": true, "subscriber_count": 0, "effectiveness_score": 0.87, "pass_rate": 0.91, "success_rate": 0.93, "trend": "up", "source_type": "platform", "created_at": "2026-04-01T09:00:00Z" } ], "total": 8 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nskills = router.list_skills(category=\"tools\", limit=50)" }, { "lang": "Bash", "label": "CLI", "source": "decimalai skills list --limit 50" } ] } }, "/api/v1/skills/sync": { "post": { "tags": [ "skills" ], "summary": "Reconcile a batch of local skills with the platform", "description": "One endpoint, two consumers:\n\n- **SDK auto-discovery** (CI, agent boot): defaults are right.\n Send `{\"skills\": [...]}` and read `created` / `updated` / `unchanged` counts.\n- **Interactive CLI** (`decimalai skills sync ./skills/`): pass\n `response_mode=\"diff\"` to get a per-skill `actions` array including\n `body_markdown` for any skill where the remote version is newer\n (so the CLI can overwrite local files).\n\nConflict policy: with `conflict_policy=\"newer_wins\"` (default), the\nside whose timestamp is later wins — best for human-in-the-loop CLI.\nFor CI/SDK pipelines where the repo is the source of truth, pass\n`conflict_policy=\"local_wins\"` to force every push. `remote_wins` is\nthe inverse — useful for \"treat the platform as canonical.\"\n\nEmpty bodies are 422'd at Pydantic validation. Invalid names are\n409'd at the same layer. Per-skill issues that survive validation\n(e.g. a transient DB error) land in the `failures` array; the rest\nof the batch still processes.\n\n`content_hash` on each entry is optional — clients that already\ncomputed SHA-256 (CLI walking a directory) can pass it to save a\nserver-side hash; clients that didn't (SDK auto-discovery) can omit.", "operationId": "sync_skills_api_v1_skills_sync_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSkillsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSkillsResponse" }, "example": { "status": "ok", "created": 2, "updated": 1, "unchanged": 5, "pulled": 0, "failures": [] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\nfrom decimalai.skills import discover_skills\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nlocal_skills = discover_skills(base_path=\"./skills\")\nrouter.sync_skills(skills=local_skills)" }, { "lang": "Bash", "label": "CLI", "source": "decimalai skills sync --dir ./skills" } ] } }, "/api/v1/skills/installs": { "get": { "tags": [ "skills" ], "summary": "Per-install skill sync-divergence state", "description": "Per-install divergence pills for the org's skills (#9).\n\nEach install lists its skills with a ``status`` — ``in_sync``,\n``local_ahead`` (push), ``remote_ahead`` (pull), ``conflict`` (reconcile),\n``local_only``, or ``unknown`` — plus a ``counts`` rollup for the bar.\nStrictly org-scoped: a caller never sees another tenant's installs.", "operationId": "list_skill_installs_api_v1_skills_installs_get", "parameters": [ { "name": "install_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single install_id.", "title": "Install Id" }, "description": "Filter to a single install_id." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInstallsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/installs/report": { "post": { "tags": [ "skills" ], "summary": "Report an install's local skill hashes (no push)", "description": "Refresh an install's locally-observed hashes without pushing anything.\n\nRead-only with respect to skills/versions: it only updates the install's\ndivergence rows so a future ``decimalai skills status`` can show drift\npills. Unknown skill names come back as ``local_only`` and are not\npersisted (no skill to attach them to).", "operationId": "report_skill_install_api_v1_skills_installs_report_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportInstallRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportInstallResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/menu": { "get": { "tags": [ "skills" ], "summary": "Get the skill menu (Free tier)", "description": "Get the full skill menu for prompt injection (Free tier).\n\nReturns the agent's active skills with name + description and a\nready-to-use prompt fragment, scoped by the Use/Fork resolver. When\n``agent_name`` is supplied, that agent's agent-scope Use rows are included.", "operationId": "get_menu_api_v1_skills_menu_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category (e.g. 'tools', 'policies').", "examples": [ "tools" ], "title": "Category" }, "description": "Filter by category (e.g. 'tools', 'policies')." }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single project.", "title": "Project Id" }, "description": "Filter to a single project." }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the menu to one agent (Use/Fork resolver) — agent-scope Use rows for that agent are included.", "title": "Agent Name" }, "description": "Scope the menu to one agent (Use/Fork resolver) — agent-scope Use rows for that agent are included." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "skills": [ { "name": "search-flights", "category": "tools", "description": "Search available flights", "is_active": true }, { "name": "book-flights", "category": "tools", "description": "Book a flight by ID", "is_active": true } ], "total": 8, "prompt_fragment": "You have access to 8 skills..." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nmenu = router.get_menu(category=\"tools\")" } ] } }, "/api/v1/skills/route": { "post": { "tags": [ "skills" ], "summary": "Smart-route a query to the best skill", "description": "Smart routing: semantic search + performance re-ranking (Pro tier).\n\nEmbeds the query, finds relevant skills via cosine similarity,\nthen re-ranks by historical performance data.\n\nIf `include_attachments` is true (default), the response includes\nbundled script content for skills that have multi-file bundles.", "operationId": "smart_route_api_v1_skills_route_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" }, "examples": { "search": { "summary": "Route a user query", "value": { "query": "Find flights to Tokyo", "top_k": 5, "include_attachments": true } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "matched_skill": "search-flights", "confidence": 0.92, "alternatives": [ { "name": "book-flights", "score": 0.45 } ], "attachments": [] } } } }, "400": { "description": "Missing `query` field in the request body." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nresult = router.smart_route(query=\"Find flights to Tokyo\", top_k=5)" } ] } }, "/api/v1/skills/reembed": { "post": { "tags": [ "skills" ], "summary": "Re-embed all skills using a different embedding model", "description": "Re-embed all skills using a different embedding model.\n\nUsed when switching embedding models. Source text is always\nretained, so this is a lossless recompute.", "operationId": "reembed_skills_api_v1_skills_reembed_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/export": { "get": { "tags": [ "skills" ], "summary": "Export org skills with full content", "description": "Export org skills with full content + attachments for disk write.\n\nReturns skill data in a format ready for the SDK's `export_to_disk()`.\nEach skill includes its `body_markdown` and all attachment file contents.", "operationId": "export_skills_api_v1_skills_export_get", "parameters": [ { "name": "names", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated skill names to export. If omitted, exports all.", "title": "Names" }, "description": "Comma-separated skill names to export. If omitted, exports all." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "skills": [ { "id": "sk_abc123", "name": "search-flights", "description": "Search available flights", "body_markdown": "# Search Flights\n\n...", "version": 3, "content_hash": "a1b2c3d4e5f60718", "category": "tools", "license": "MIT", "attachments": [], "source": "platform" } ], "total": 12 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nrouter.export_to_disk(output_dir=\"./skills\")" } ] } }, "/api/v1/skills/hashes": { "get": { "tags": [ "skills" ], "summary": "Get content hashes for all org skills", "description": "Get content hashes for all org skills.\n\nUsed by the SDK for efficient batch status checks —\ncompare local hashes to platform hashes without downloading\nfull skill content.\n\nReturns:\n { \"hashes\": {\"skill-name\": {\"hash\": \"abc123\", \"version\": 2}, ...} }", "operationId": "get_skill_hashes_api_v1_skills_hashes_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}": { "get": { "tags": [ "skills" ], "summary": "Get a skill by name", "description": "Get skill metadata, ownership, and analytics.", "operationId": "get_skill_api_v1_skills__skill_name__get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "description": "The skill's slug-style name (lowercase, hyphens/underscores).", "examples": [ "search-flights" ], "title": "Skill Name" }, "description": "The skill's slug-style name (lowercase, hyphens/underscores)." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDetail" }, "example": { "id": "sk_abc123", "name": "search-flights", "description": "Search available flights", "category": "tools", "stability": "stable", "is_active": true, "trigger_phrases": [ "find flights" ], "embedding_model": "text-embedding-3-small", "embedding_dimensions": 1536, "latest_version": { "version_number": 3, "content_hash": "a1b2c3d4e5f60718", "change_summary": "Added retry logic on timeout", "author": "alice@example.com", "created_at": "2026-05-10T14:22:00Z" }, "created_at": "2026-04-01T09:00:00Z", "owner": { "user_id": "user_123", "user_name": "Alice", "workspace_id": "ws_main", "workspace_name": "Main" }, "visibility": "org", "can_edit": true, "can_share": true, "activation_count": 142, "effectiveness_score": 0.87, "pass_rate": 0.91, "success_rate": 0.93, "trend": "up" } } } }, "404": { "description": "Skill not found, or hidden from the caller by visibility rules." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nskill = router.get_skill(\"search-flights\")" } ] } }, "/api/v1/skills/{skill_name}/exists": { "get": { "tags": [ "skills" ], "summary": "Existence probe with get_skill's exact access rules", "description": "200 + {\"exists\": bool} — never 404.\n\nThe skill-detail page decides org-member vs public-visitor mode by\nprobing for the slug in the caller's org. A GET-by-name probe logged a\nbrowser-console 404 for every non-installed registry skill (F23, deep\naudit 2026-06-10), and the list endpoint's `?name=` filter has DIFFERENT\nvisibility semantics (it hides workspace-scoped skills from callers\nwithout membership, where get_skill's can_view_skill allows them — the\ncuj-43 Phase-3 walkthrough caught that as a mode regression). This probe\nreuses get_skill's exact resolution + visibility check.", "operationId": "skill_exists_api_v1_skills__skill_name__exists_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/body": { "get": { "tags": [ "skills" ], "summary": "Get the full body markdown of a skill for prompt injection", "description": "Get the full body markdown of a skill for prompt injection.", "operationId": "get_skill_body_api_v1_skills__skill_name__body_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Version number (default: latest)", "title": "Version" }, "description": "Version number (default: latest)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/generate-starter-tests": { "post": { "tags": [ "skills" ], "summary": "Opt-in: generate platform-authored starter test cases for this skill", "description": "Explicit-opt-in entry point for platform test generation.\n\nCalled from three UI surfaces (per the no-background-auto-gen\npolicy):\n - \"✨ Generate starter cases\" checkbox on the new-skill form\n - Benchmark tab empty-state dual CTA\n - Publish dialog rescue path when C10 fires with no benchmark run\n\nIdempotent: if the latest version already has any SkillTestCase\nrows, returns the existing count without calling the LLM.", "operationId": "generate_skill_starter_tests_api_v1_skills__skill_name__generate_starter_tests_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/test-cases": { "get": { "tags": [ "skills" ], "summary": "List the benchmark test cases on this skill's latest version", "operationId": "list_skill_test_cases_api_v1_skills__skill_name__test_cases_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "skills" ], "summary": "Author a single benchmark test case in the browser", "operationId": "create_skill_test_case_api_v1_skills__skill_name__test_cases_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TestCaseBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/test-cases/{case_id}": { "put": { "tags": [ "skills" ], "summary": "Edit a single benchmark test case", "operationId": "update_skill_test_case_api_v1_skills__skill_name__test_cases__case_id__put", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Case Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TestCaseBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "skills" ], "summary": "Delete a single benchmark test case", "operationId": "delete_skill_test_case_api_v1_skills__skill_name__test_cases__case_id__delete", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Case Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/benchmark/run": { "post": { "tags": [ "skills" ], "summary": "Run the A/B benchmark suite for this skill's latest version", "description": "Phase 3 — Benchmark runner trigger.\n\nSynchronously runs every SkillTestCase for the skill's latest version\nagainst the configured agent stub, with skill and without. Returns\nthe SkillTestRun including per-case results. Caller can poll the\nresults endpoint or just consume the returned payload.", "operationId": "run_skill_benchmark_api_v1_skills__skill_name__benchmark_run_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "triggered_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Where this run was kicked off from", "default": "api", "title": "Triggered By" }, "description": "Where this run was kicked off from" }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override the agent-arm model (e.g. claude-haiku-4-5 for the model-relative lane). Must be in GET /api/v1/auth/models. Default: the platform's configured model. The executed model is recorded as runner_model on the run.", "title": "Model" }, "description": "Override the agent-arm model (e.g. claude-haiku-4-5 for the model-relative lane). Must be in GET /api/v1/auth/models. Default: the platform's configured model. The executed model is recorded as runner_model on the run." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/benchmark/spotcheck": { "post": { "tags": [ "skills" ], "summary": "Spot-check a replay run: re-run K random cases on our key → upgrade to trustless or flag", "description": "Upgrade a verify-by-replay run to the trustless tier (or flag it).\n\nRe-runs K random cases on the platform's own key and compares pass/fail to what the\npublisher submitted. Within tolerance → `verification_method='spotcheck'`; diverges →\nthe run is un-verified (drops from the leaderboard) with the divergence recorded.\nUses real LLM (K×2 calls, logged to the usage ledger).", "operationId": "spotcheck_skill_benchmark_api_v1_skills__skill_name__benchmark_spotcheck_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "run_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Replay run to spot-check; default: the skill's latest replay run.", "title": "Run Id" }, "description": "Replay run to spot-check; default: the skill's latest replay run." }, { "name": "k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1, "description": "Number of random cases to re-run on the platform.", "default": 5, "title": "K" }, "description": "Number of random cases to re-run on the platform." }, { "name": "tolerance", "in": "query", "required": false, "schema": { "type": "number", "maximum": 1, "minimum": 0, "description": "Max arm-mismatch fraction tolerated (LLM nondeterminism).", "default": 0.2, "title": "Tolerance" }, "description": "Max arm-mismatch fraction tolerated (LLM nondeterminism)." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/benchmark/import": { "post": { "tags": [ "skills" ], "summary": "Import a locally produced skillevaluation results.json (unverified)", "description": "Open-runner funnel: persist a local `skillevaluation run` result.\n\nThe run is stored **unverified** (`triggered_by='local_import'`) — it\nshows on this skill's own Benchmark tab but never feeds registry\nrollups, rankings, or public cards. Run the hosted benchmark (or\npublish, which triggers a verification run) to get a verified result.\n\nFree and meter-exempt: importing is a JSON write, not an execution —\nno LLM spend happens here, so no benchmark quota is consumed.\n\nPushed cases are matched to this skill's latest-version eval cases by\nname; unmatched names are reported in `skipped_cases` (usually a sign\nthe local eval.yaml is ahead of the last `decimalai skills sync`).", "operationId": "import_skill_benchmark_api_v1_skills__skill_name__benchmark_import_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "A results document conforming to skillevaluation's test-run-result schema, as written by `skillevaluation run`.", "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/benchmark/results": { "get": { "tags": [ "skills" ], "summary": "List recent benchmark runs for this skill", "description": "Returns the N most-recent SkillTestRun rows + their per-case results.\n\nUsed by the Benchmark tab (mockup 5.3) to render the regression-aware\nA/B table. Most recent run is always at index 0.", "operationId": "list_skill_benchmark_results_api_v1_skills__skill_name__benchmark_results_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/health-summary": { "get": { "tags": [ "skills" ], "summary": "Unified Skill Health card payload (mockup 5.2)", "description": "One payload that drives the SkillHealthHeader card.\n\nAggregates:\n - Phase 3 benchmark: latest run verdict + pass rate + lift + last_run_at\n - Phase 2 live traces: avg rating + count rated + discoverability gap\n + last_rater_run_at\n - Phase 4 suggested edits: count of `status='draft'` rows\n\nEach block is nullable so the UI can degrade gracefully — a brand-new\nskill with no benchmarks shows the live-traces block alone, etc.", "operationId": "get_skill_health_summary_api_v1_skills__skill_name__health_summary_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/suggested-edits": { "get": { "tags": [ "skills" ], "summary": "List drafted suggested edits for this skill", "operationId": "list_suggested_edits_api_v1_skills__skill_name__suggested_edits_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter: draft|accepted|rejected|superseded|all", "default": "draft", "title": "Status" }, "description": "Filter: draft|accepted|rejected|superseded|all" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/suggested-edits/{edit_id}/accept": { "post": { "tags": [ "skills" ], "summary": "Accept a suggested edit → new SkillVersion + regression tests + benchmark", "description": "Close the loop: apply the patch, create v(N+1), generate regression\ntests from supporting traces, kick off a benchmark run.", "operationId": "accept_suggested_edit_api_v1_skills__skill_name__suggested_edits__edit_id__accept_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "edit_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Edit Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/suggested-edits/{edit_id}/reject": { "post": { "tags": [ "skills" ], "summary": "Reject a suggested edit", "operationId": "reject_suggested_edit_api_v1_skills__skill_name__suggested_edits__edit_id__reject_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "edit_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Edit Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/live-traces-summary": { "get": { "tags": [ "skills" ], "summary": "Per-skill Live Traces summary — effectiveness distribution + discoverability gap", "description": "Drives mockup 5.4 — the Live Traces tab on /skills/.\n\nReturns the effectiveness histogram (1–10 buckets), the\ndiscoverability gap %, and the top patterns. All scoped to the\nrequesting org's traces over the requested window.", "operationId": "get_skill_live_traces_summary_api_v1_skills__skill_name__live_traces_summary_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/patterns": { "get": { "tags": [ "skills" ], "summary": "List all open struggle Patterns for this skill", "description": "Drives the \"View all N patterns\" drilldown.", "operationId": "list_skill_patterns_api_v1_skills__skill_name__patterns_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/playground-run": { "post": { "tags": [ "skills" ], "summary": "Test whether a hypothetical user input would activate this skill, and preview the rendered body", "description": "Standalone test surface for a skill (CUJ 26).\n\nBody:\n user_input: str (required) — the hypothetical user message\n variables: dict[str, str] (optional) — values for {{var}} placeholders\n version_id: str (optional) — pin to a specific skill_version; default = latest\n\nResponse:\n {\n would_activate: bool,\n matched_triggers: [str, ...], # the trigger_phrases that matched (substring)\n rendered_body: str, # body with variables substituted\n missing_variables: [str, ...], # {{var}} placeholders the caller didn't fill\n skill: {id, name, version_number, content_hash}\n }\n\nActivation rule (V1): if any `trigger_phrases` entry appears as a\ncase-insensitive substring of `user_input`, the skill activates.\nSkills with no trigger_phrases always activate (unconditional). This\nmirrors the SDK's default SkillRouter substring path. Embedding-\nbased matching is a separate concern (uses `body_embedding`); not\nplumbed into this endpoint yet.", "operationId": "skill_playground_run_api_v1_skills__skill_name__playground_run_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/versions": { "get": { "tags": [ "skills" ], "summary": "List versions of a skill", "description": "List all versions of a skill, newest first.", "operationId": "list_versions_api_v1_skills__skill_name__versions_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "description": "The skill's slug-style name.", "examples": [ "search-flights" ], "title": "Skill Name" }, "description": "The skill's slug-style name." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVersionsResponse" }, "example": { "skill_name": "search-flights", "versions": [ { "id": "sv_v3", "version_number": 3, "content_hash": "a1b2c3d4e5f60718", "body_markdown": "# Search Flights\n\n## When to activate ...", "description": "Search available flights", "change_summary": "Added retry logic on timeout", "author": "alice@example.com", "created_at": "2026-05-10T14:22:00Z" } ] } } } }, "404": { "description": "Skill not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nversions = router.list_versions(\"search-flights\")" } ] } }, "/api/v1/skills/{skill_name}/version-usage": { "get": { "tags": [ "skills" ], "summary": "Per-version usage breakdown (audit#326 Weave-framing finding)", "description": "Per-version usage stats: subscription_count + activation_count\n+ agent_count per version. Lets the registry Versions UI render a\n\"which version is production-active\" column without sending the\nfull subscription list to the client.", "operationId": "get_version_usage_api_v1_skills__skill_name__version_usage_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/versions/{version_number}": { "get": { "tags": [ "skills" ], "summary": "Get a specific version's full content.\"\"\"", "description": "Get a specific version's full content.", "operationId": "get_version_api_v1_skills__skill_name__versions__version_number__get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "version_number", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version Number" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/versions/{version_a}/diff/{version_b}": { "get": { "tags": [ "skills" ], "summary": "Compute a unified diff between two skill versions", "description": "Compute a unified diff between two skill versions.\n\nReturns line-by-line diff and summary statistics.", "operationId": "diff_versions_api_v1_skills__skill_name__versions__version_a__diff__version_b__get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "version_a", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version A" } }, { "name": "version_b", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version B" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}": { "put": { "tags": [ "skills" ], "summary": "Update a skill", "description": "Update a skill. Creates a new version if body content changes.\n\nEnforces ownership: only the creator, owning workspace editors,\nor org admins can modify.\nStability must be one of: `stable`, `experimental`, `deprecated`.", "operationId": "update_skill_api_v1_skills__skill_id__put", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The skill's stable ID (prefixed 'sk_').", "examples": [ "sk_abc123" ], "title": "Skill Id" }, "description": "The skill's stable ID (prefixed 'sk_')." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillResponse" }, "example": { "status": "ok", "skill_id": "sk_abc123", "name": "search-flights", "latest_version_id": "sv_v4" } } } }, "403": { "description": "Caller is not the owner or a workspace editor." }, "404": { "description": "Skill not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nrouter.update_skill(\n skill_id=\"sk_abc123\",\n body_markdown=\"Updated skill content...\",\n change_summary=\"Tightened the retry guidance.\",\n)" } ] }, "delete": { "tags": [ "skills" ], "summary": "Delete a skill (soft-delete)", "description": "Soft-delete a skill (sets `is_active=False`).\n\nExisting trace attributions are preserved, but the skill no longer appears\nin the active list and cannot be activated by agents.\n\n**Destructive for future runs** — agents that depend on this skill will\nfail to resolve it. Check `activation_count` from the list endpoint first.\n\nEnforces ownership: only the creator or org admins can delete.", "operationId": "delete_skill_api_v1_skills__skill_id__delete", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The skill's stable ID (prefixed 'sk_').", "examples": [ "sk_abc123" ], "title": "Skill Id" }, "description": "The skill's stable ID (prefixed 'sk_')." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSkillResponse" }, "example": { "status": "ok", "deleted": true } } } }, "403": { "description": "Only the skill creator or org admin can delete." }, "404": { "description": "Skill not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "from decimalai.skill_router import SkillRouter\n\nrouter = SkillRouter(api_key=\"dai_sk_...\")\nrouter.delete_skill(\"sk_abc123\")" } ] } }, "/api/v1/skills/{skill_id}/rename": { "post": { "tags": [ "skills" ], "summary": "Rename a skill", "description": "Rename a skill. The new name must be unique within the requester's org.\n\n2026-06-01 — added to support publish-with-rename in PublishDialog.\nOther tables reference skills by ID, so this is a single-row update on\n`skills.name`. No cascading writes; agent bindings, fork lineage,\nSkillShare grants, and install records continue to point at the same ID.\n\nEnforces edit permission: only the creator, owning workspace editors,\nor org admins can rename.", "operationId": "rename_skill_route_api_v1_skills__skill_id__rename_post", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The skill's stable ID (prefixed 'sk_').", "examples": [ "sk_abc123" ], "title": "Skill Id" }, "description": "The skill's stable ID (prefixed 'sk_')." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSkillRequest" } } } }, "responses": { "200": { "description": "Skill renamed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSkillResponse" } } } }, "403": { "description": "Caller is not the owner or a workspace editor." }, "404": { "description": "Skill not found." }, "409": { "description": "A skill with the new name already exists in the org." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/analytics/metrics": { "get": { "tags": [ "skills" ], "summary": "Per-skill performance metrics with baseline comparison", "description": "Per-skill performance metrics with baseline comparison.", "operationId": "get_skill_metrics_api_v1_skills_analytics_metrics_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "skill_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/analytics/compare": { "get": { "tags": [ "skills" ], "summary": "Compare two versions of a skill", "description": "Compare two versions of a skill.", "operationId": "compare_versions_api_v1_skills_analytics_compare_get", "parameters": [ { "name": "skill_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "baseline_hash", "in": "query", "required": true, "schema": { "type": "string", "title": "Baseline Hash" } }, { "name": "candidate_hash", "in": "query", "required": true, "schema": { "type": "string", "title": "Candidate Hash" } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 60, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/analytics/leaderboard": { "get": { "tags": [ "skills" ], "summary": "Rank skills by effectiveness", "description": "Rank skills by effectiveness.", "operationId": "get_leaderboard_api_v1_skills_analytics_leaderboard_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/analytics/timeline": { "get": { "tags": [ "skills" ], "summary": "Daily skill activation timeline for an agent", "description": "Daily skill activation timeline for an agent.\n\nReturns per-day activation counts for each skill assigned to\nthe given agent over the requested window. Powers the timeline\nvisualization on the agent Skills dashboard.", "operationId": "get_skill_timeline_api_v1_skills_analytics_timeline_get", "parameters": [ { "name": "agent_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/router-stats": { "get": { "tags": [ "skills" ], "summary": "Per-skill offered-vs-activated rollup (CUJ-38 Phase 3)", "description": "Rollup the org's routing decisions that offered `skill_name` and\nmeasure how often a downstream trace actually activated it.\n\nThe contract that turns the per-decision join (CUJ-38 Phase 2) into\na \"menu bloat\" signal a dashboard can show. Returns:\n\n {\n decisions_count, offered_count, activated_count,\n offered_not_activated_count, activation_rate, window_days\n }\n\nOrg-scoped (no cross-org leakage). Cold-start orgs (no routing data)\nreturn zeros with `activation_rate=None` — the frontend renders a\n\"no data yet\" placeholder rather than a 0% bar.", "operationId": "get_skill_router_stats_api_v1_skills__skill_name__router_stats_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/routing/config": { "get": { "tags": [ "skills" ], "summary": "Get current routing configuration and readiness status", "description": "Get current routing configuration and readiness status.\n\nReturns embedding config, performance weights, and whether\nsmart routing is available (requires embeddings).", "operationId": "get_routing_config_api_v1_skills_routing_config_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/routing/{routing_id}": { "get": { "tags": [ "skills" ], "summary": "Offered-vs-activated join for a single routing decision (CUJ-38)", "description": "Resolve the offered-vs-activated answer for a single router call.\n\nJoins three things:\n 1. `routing_decision` row keyed on `routing_id` — what skills the\n router offered.\n 2. `run_trace` rows whose `routing_id` matches — the agent run(s)\n the SDK linked back.\n 3. `trace_skill_activation` rows for those traces — what the LLM\n actually picked.\n\nReturns 404 if no `routing_decision` exists for the ID (e.g., a\nfabricated ID, or the decision was GC'd). Multiple traces with the\nsame routing_id are unusual but supported — the activated set is\nthe union across them.", "operationId": "get_routing_decision_api_v1_skills_routing__routing_id__get", "parameters": [ { "name": "routing_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Routing Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/subscribe": { "post": { "tags": [ "skills" ], "summary": "Deprecated alias of /assign (subscribe → assign, Use/Fork consolidation)", "description": "Subscribe an agent to a skill.\n\nCreates a SkillSubscription linking the agent to the skill.\nOptional: pin to a specific version for stability.", "operationId": "subscribe_to_skill_api_v1_skills__skill_name__subscribe_post", "deprecated": true, "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "skills" ], "summary": "Unsubscribe an agent from a skill", "description": "Unsubscribe an agent from a skill.", "operationId": "unsubscribe_from_skill_api_v1_skills__skill_name__subscribe_delete", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/assign": { "post": { "tags": [ "skills" ], "summary": "Assign a skill to an agent (an agent-scope Use)", "description": "Subscribe an agent to a skill.\n\nCreates a SkillSubscription linking the agent to the skill.\nOptional: pin to a specific version for stability.", "operationId": "assign_skill_to_agent_api_v1_skills__skill_name__assign_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/subscriptions": { "get": { "tags": [ "skills" ], "summary": "List all agents subscribed to a skill (canonical REST plural; improve#628)", "description": "List all agents subscribed to a skill.\n\nimprove#628 — closes discovery/cuj23_skill_governance_officer/\nno-skills-subscriptions-list-endpoint. The canonical REST plural\npath `/{name}/subscriptions` now aliases the existing\n`/{name}/subscribers` handler. Also exposes `subscribed_by_user_id`\nso governance officers can answer \"who attached this skill?\".", "operationId": "get_subscribers_api_v1_skills__skill_name__subscriptions_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/subscribers": { "get": { "tags": [ "skills" ], "summary": "List all agents subscribed to a skill", "description": "List all agents subscribed to a skill.\n\nimprove#628 — closes discovery/cuj23_skill_governance_officer/\nno-skills-subscriptions-list-endpoint. The canonical REST plural\npath `/{name}/subscriptions` now aliases the existing\n`/{name}/subscribers` handler. Also exposes `subscribed_by_user_id`\nso governance officers can answer \"who attached this skill?\".", "operationId": "get_subscribers_api_v1_skills__skill_name__subscribers_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/impact": { "get": { "tags": [ "skills" ], "summary": "Impact analysis: show how many agents would be affected by a skill change", "description": "Impact analysis: show how many agents would be affected by a skill change.\n\nReturns counts of subscribers on latest vs. pinned versions.\nUsed by the UI to show a confirmation dialog before editing.", "operationId": "get_impact_api_v1_skills__skill_name__impact_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/analytics.csv": { "get": { "tags": [ "skills" ], "summary": "Export skill analytics as CSV for stakeholder reports", "description": "Closes discovery/cuj21_data_analyst_exporter/skill-detail-no-csv-export (improve#579).\n\nReturns a summary CSV (one row) with the headline metrics shown on the\nskill detail page. Suitable for pasting into stakeholder reports.\nExperiment-level rows (per-A/B-test breakdown) are deferred to a\nseparate cycle — this initial version covers the persona's primary\n`analytics_verified_and_exported` verdict for the headline numbers.", "operationId": "export_analytics_csv_api_v1_skills__skill_name__analytics_csv_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/transfer": { "post": { "tags": [ "skills" ], "summary": "Transfer skill ownership to a different workspace", "description": "Transfer skill ownership to a different workspace.\n\nOnly the creator or org admins can transfer.", "operationId": "transfer_skill_api_v1_skills__skill_name__transfer_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/fork": { "post": { "tags": [ "skills" ], "summary": "Fork a skill — create an independent copy in the caller's workspace", "description": "Fork a skill — create an independent copy in the caller's workspace.\n\nThe forked skill:\n- Gets a unique name (e.g. 'code-review-data-team' or user-supplied)\n- Copies the latest version body\n- Tracks its origin via forked_from_skill_id + forked_at_version_id\n- Is owned by the caller's workspace\n- Always gets 'org' visibility (even if source is 'public')\n\nFor registry installs, also:\n- Blocks duplicate installs from the same source skill\n- Atomically increments install_count on the source skill", "operationId": "fork_skill_api_v1_skills__skill_name__fork_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkSkillRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/shares": { "get": { "tags": [ "skills" ], "summary": "List all sharing grants for a skill", "description": "List all sharing grants for a skill.", "operationId": "list_skill_shares_api_v1_skills__skill_name__shares_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "skills" ], "summary": "Add a sharing grant to a skill", "description": "Add a sharing grant to a skill.\n\nBody:\n grant_type: 'user' | 'workspace'\n grantee_id: user_id or workspace_id\n access_level: 'view' | 'edit' | 'admin' (default: 'view')", "operationId": "add_skill_share_api_v1_skills__skill_name__shares_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/shares/{share_id}": { "delete": { "tags": [ "skills" ], "summary": "Remove a sharing grant from a skill", "description": "Remove a sharing grant from a skill.", "operationId": "remove_skill_share_api_v1_skills__skill_name__shares__share_id__delete", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/publish": { "post": { "tags": [ "skills" ], "summary": "Publish a skill to the public registry", "description": "Publish a skill to the public registry.\n\nPre-checks:\n- Must be the skill creator or org admin\n- C10 benchmark-presence gate: eval cases authored + a completed benchmark run\n- Safety scan must pass; name must not collide with an existing public skill\n\nThe former ≥3-versions and ≥10-activations gates were removed (2026-06-14): at\npublish time the only activations a skill can have are the author's own, so the\ncount gated on a gameable self-signal, not community evidence — and the evidence\ntiering already lives in the registry ranking (the \"recommended\" sort surfaces\nskills with ≥10 activations earned in real, post-publish use). The C10 gate below\nstill ensures a skill was actually tested (eval + run) before it can publish.", "operationId": "publish_skill_api_v1_skills__skill_name__publish_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "category", "in": "query", "required": true, "schema": { "type": "string", "description": "Registry category (e.g. 'code-review')", "title": "Category" }, "description": "Registry category (e.g. 'code-review')" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated tags", "default": "", "title": "Tags" }, "description": "Comma-separated tags" }, { "name": "author_display_name", "in": "query", "required": false, "schema": { "type": "string", "description": "Author display name for registry", "default": "", "title": "Author Display Name" }, "description": "Author display name for registry" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/unpublish": { "post": { "tags": [ "skills" ], "summary": "Remove a skill from the public registry", "description": "Remove a skill from the public registry.\n\nExisting forks remain unaffected (they are independent copies).", "operationId": "unpublish_skill_api_v1_skills__skill_name__unpublish_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/harvest": { "post": { "tags": [ "skills" ], "summary": "Failure-first harvest: run a skill's eval cases on the BASE model to see if the base already passes", "description": "Answer \"should this skill exist?\" before benchmarking/publishing it.\n\nRuns the BASE model alone (no skill body) over the skill's latest version's eval\ncases and returns a verdict — ``build`` (the base fails, so the skill has room to\nlift), ``skip`` (the base already passes >= 80%, so the skill is unlikely to\nhelp), or ``invalid_errors`` (too many provider errors to judge) — plus the base\npass-rate and per-case detail.\n\nCalls the LLM once per eval case, so it is gated (owner-only) and METERED against\nthe org's monthly benchmark-run allowance (HTTP 429 when exhausted) — the usage\nlimit that kept it off the customer surface until now. NB: runs synchronously;\nfor large suites move it to a background job (follow-up).", "operationId": "harvest_skill_api_v1_skills__skill_name__harvest_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/upstream-status": { "get": { "tags": [ "skills" ], "summary": "Check if the forked skill has upstream updates available", "description": "Check if the forked skill has upstream updates available.\n\nReturns cached data from the daily background job.", "operationId": "get_upstream_status_api_v1_skills__skill_name__upstream_status_get", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_name}/merge-upstream": { "post": { "tags": [ "skills" ], "summary": "Merge upstream changes into a forked skill", "description": "Merge upstream changes into a forked skill.\n\nModes:\n- 'preview': Returns the upstream body for side-by-side comparison\n- 'replace': Overwrites the fork's body with upstream content", "operationId": "merge_upstream_api_v1_skills__skill_name__merge_upstream_post", "parameters": [ { "name": "skill_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Name" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "description": "Merge mode: 'replace' or 'preview'", "default": "replace", "title": "Mode" }, "description": "Merge mode: 'replace' or 'preview'" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/import-skillmd": { "post": { "tags": [ "skills" ], "summary": "Import a skill from a SKILL.md file content", "description": "Import a skill from a SKILL.md file content.\n\nParses YAML frontmatter for name, description, category, and tags,\nthen creates the skill and its first version in the caller's org.\n\nRequest body:\n {\n \"content\": \"---\\nname: my-skill\\n...\\n---\\n# My Skill\\n...\",\n \"workspace_id\": \"optional-workspace-id\"\n }\n\nReturns the created skill_id, name, and parsed metadata.", "operationId": "import_skillmd_api_v1_skills_import_skillmd_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{name}/export-skillmd": { "get": { "tags": [ "skills" ], "summary": "Export a skill as a standard SKILL.md file", "description": "Export a skill as a standard SKILL.md file.\n\nGenerates a SKILL.md with YAML frontmatter and the full body markdown.\nThe caller must have view access to the skill.\n\nReturns:\n { \"filename\": \"my-skill.SKILL.md\", \"content\": \"---\\n...\" }", "operationId": "export_skillmd_api_v1_skills__name__export_skillmd_get", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/telemetry/event": { "post": { "tags": [ "telemetry" ], "summary": "Ingest a telemetry event", "description": "Ingest a client-side telemetry event from the dashboard.\n\nCurrently a no-op: returns `204 No Content` without parsing or\npersisting the body. Exists so frontend `track()` calls don't 404\nagainst the backend. Auth is not required — events are anonymous\nby design.", "operationId": "ingest_event_api_v1_telemetry_event_post", "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Malformed event payload" } } } }, "/api/v1/traces": { "post": { "tags": [ "traces" ], "summary": "Ingest a trace", "description": "Ingest a single trace from the SDK.\n\n## Data Model\n\nA trace contains two types of children:\n\n- **`spans`** — represent operations (agent steps, tool calls, chains).\n Nest via `parent_span_id` to form a tree.\n- **`llm_calls`** — represent individual LLM invocations with full fidelity\n (model, tokens, messages, response). Link to a parent span via `span_id`.\n\n## Structuring Rules\n\n**Spans** should be used for containers and non-LLM operations:\n\n| `span_type` | Use for | Example |\n|-------------|---------|---------|\n| `agent` | Top-level agent invocation (root span) | `finance-research-agent` |\n| `tool` | Tool/function execution | `get_stock_price` |\n| `chain` | Multi-step pipeline or sub-chain | `research-pipeline` |\n| `retrieval` | RAG retrieval step | `vector-search` |\n| `llm` | Wrapper span for an LLM call (optional) | `LLM: plan step 1` |\n\n**LLM calls** should be used for every LLM invocation:\n\n- Always set `span_id` to the parent span that triggered this call\n- Include `rendered_input` (list of messages), `output`, `model_name`, `provider`\n- Include `started_at`/`ended_at` for timeline visualization\n- Include token counts (`input_tokens`, `output_tokens`) for cost tracking\n\n## Tree Rendering\n\nThe frontend builds a unified tree from both tables:\n\n1. If an `llm_call` has `span_id` matching a span → it enriches that span\n (shown as one node with LLM details in a tab)\n2. If an `llm_call` has no matching span → shown as a standalone 🧠 node\n under the root span\n3. All children are sorted by `started_at` for chronological order\n\n## Example Structure\n\n```\nagent-step (span, type=agent)\n ├── llm_call_1 (llm_call, span_id=agent-step)\n ├── tool-span (span, type=tool, parent_span_id=agent-step)\n └── llm_call_2 (llm_call, span_id=agent-step)\n```\n\nReturns 409 if a trace with the same ID already exists.", "operationId": "ingest_trace_api_v1_traces_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Ingestion result with counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Ingest Trace Api V1 Traces Post" }, "example": { "status": "ok", "id": "trc_abc123", "trace_id": "trc_abc123", "agent_name": "my-agent", "spans": 5, "llm_calls": 3 } } } }, "400": { "description": "Trace validation failed." }, "402": { "description": "Plan trace-ingest quota exhausted." }, "409": { "description": "A trace with this ID already exists." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import decimalai\n\n# Auto-instrumentation (recommended)\ndecimalai.init(api_key=\"dai_sk_...\", openai_agents=True)\n\n# Or manual tracing with decorator\n@decimalai.trace(agent_name=\"my-agent\")\ndef run_agent(query: str) -> str:\n return llm.invoke(query)\n\nrun_agent(\"What is the weather?\")" } ] }, "get": { "tags": [ "traces" ], "summary": "List traces", "description": "List traces for the project (paginated).\n\nWorkspace-scoped: filters by workspace_id when available.\nWhen target_manifest_id is provided:\n- Traces are filtered to only those that existed during the target manifest's\n active period (between its created_at and the next manifest's created_at).\n- Each trace is enriched with a `compat` object showing its compatibility\n against that manifest, computed on-demand if not already cached.\n\nMulti-agent filters:\n- child_agent_name: find parent traces where a child agent matches this name\n- child_status: further filter those children by status (e.g., 'error')", "operationId": "list_traces_api_v1_traces_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "success", "error", "degraded" ], "type": "string" }, { "type": "null" } ], "description": "Filter by trace status. Allowed: success/error/degraded.", "title": "Status" }, "description": "Filter by trace status. Allowed: success/error/degraded." }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "eval_verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by eval verdict (pass/fail/keep/drop/review/...), or 'unevaluated' for traces with no verdict yet.", "title": "Eval Verdict" }, "description": "Filter by eval verdict (pass/fail/keep/drop/review/...), or 'unevaluated' for traces with no verdict yet." }, { "name": "source_type", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "production", "test", "evaluation", "sdk", "manual", "synthetic", "development", "sandbox", "distillation", "snapshot", "file", "url", "eval_replay", "sample", "demo" ], "type": "string" }, { "type": "null" } ], "description": "Filter by trace source_type. See ingest allowlist for valid values.", "title": "Source Type" }, "description": "Filter by trace source_type. See ingest allowlist for valid values." }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Manifest Id" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full-text search across user_input, final_output, and agent_name", "title": "Search" }, "description": "Full-text search across user_input, final_output, and agent_name" }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false, drop platform-harness fixture agents (\\_\\_*, live-*, cuj*, soak-*, …) from the listing — the UI's default. Defaults to true for SDK/API back-compat. Ignored when an explicit agent/skill/tool filter is set (asking by name always works).", "default": true, "title": "Include Fixtures" }, "description": "When false, drop platform-harness fixture agents (\\_\\_*, live-*, cuj*, soak-*, …) from the listing — the UI's default. Defaults to true for SDK/API back-compat. Ignored when an explicit agent/skill/tool filter is set (asking by name always works)." }, { "name": "target_manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Show compatibility of traces relative to this manifest", "title": "Target Manifest Id" }, "description": "Show compatibility of traces relative to this manifest" }, { "name": "child_agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter parent traces by child agent name (multi-agent)", "title": "Child Agent Name" }, "description": "Filter parent traces by child agent name (multi-agent)" }, { "name": "child_status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "success", "error", "degraded" ], "type": "string" }, { "type": "null" } ], "description": "Filter child agent matches by status. Allowed: success/error/degraded (H1091).", "title": "Child Status" }, "description": "Filter child agent matches by status. Allowed: success/error/degraded (H1091)." }, { "name": "tool_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to traces that invoked the named tool (uses ToolCallIndex)", "title": "Tool Name" }, "description": "Filter to traces that invoked the named tool (uses ToolCallIndex)" }, { "name": "skill_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to traces where the named skill was activated (uses trace_skill_activation). Backs the owner skill-detail live-traces panel (improve#1413).", "title": "Skill Name" }, "description": "Filter to traces where the named skill was activated (uses trace_skill_activation). Backs the owner skill-detail live-traces panel (improve#1413)." }, { "name": "has_spans", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "H1336 (improve#702): when true, exclude traces with 0 spans (filters out empty SDK / Hello-World traces that pollute investigation views — caught by cuj07 security-sleuth at #701). When false, only return empty-span traces. Omit for both.", "title": "Has Spans" }, "description": "H1336 (improve#702): when true, exclude traces with 0 spans (filters out empty SDK / Hello-World traces that pollute investigation views — caught by cuj07 security-sleuth at #701). When false, only return empty-span traces. Omit for both." }, { "name": "has_llm_calls", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "H1336 (improve#702): symmetric filter for traces with 0 LLM calls.", "title": "Has Llm Calls" }, "description": "H1336 (improve#702): symmetric filter for traces with 0 LLM calls." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "-created_at", "created_at", "-started_at", "started_at" ], "type": "string" }, { "type": "null" } ], "description": "H1092 (improve#843): order results by the given field. Prefix '-' for descending. Defaults to '-created_at'. Unknown values 422 instead of being silently ignored.", "title": "Sort" }, "description": "H1092 (improve#843): order results by the given field. Prefix '-' for descending. Defaults to '-created_at'. Unknown values 422 instead of being silently ignored." }, { "name": "started_at_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "H1093 (improve#863): inclusive lower bound on RunTrace.started_at (ISO 8601). Malformed dates 422 via Pydantic typing instead of being silently ignored.", "title": "Started At From" }, "description": "H1093 (improve#863): inclusive lower bound on RunTrace.started_at (ISO 8601). Malformed dates 422 via Pydantic typing instead of being silently ignored." }, { "name": "started_at_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "H1093 (improve#863): inclusive upper bound on RunTrace.started_at (ISO 8601). Same validation behavior as started_at_from.", "title": "Started At To" }, "description": "H1093 (improve#863): inclusive upper bound on RunTrace.started_at (ISO 8601). Same validation behavior as started_at_from." }, { "name": "compat_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to traces with this compatibility verdict against `target_manifest_id`. Values: keep / repair / replay / drop. Requires target_manifest_id to be set for authoritative scoping; otherwise falls back to RunTrace.compat_status (a less-precise denormalized field).", "title": "Compat Status" }, "description": "Filter to traces with this compatibility verdict against `target_manifest_id`. Values: keep / repair / replay / drop. Requires target_manifest_id to be set for authoritative scoping; otherwise falls back to RunTrace.compat_status (a less-precise denormalized field)." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Traces Api V1 Traces Get" }, "example": { "traces": [ { "id": "trc_abc123", "agent_name": "travel-planner", "status": "success", "user_input": "Find flights to Tokyo", "final_output": "I found 3 flights...", "manifest_id": "mfst_001", "eval_verdict": "keep", "eval_score": 0.92, "duration_ms": 1240, "total_tokens": 850, "started_at": "2026-05-10T14:22:00Z" } ], "total": 1250, "limit": 20, "offset": 0 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\n# Search is performed via query parameters on this endpoint.\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/traces\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n params={\"agent_name\": \"my-agent\", \"eval_verdict\": \"drop\", \"limit\": 20},\n)\nresp.raise_for_status()\nfor t in resp.json()[\"traces\"]:\n print(t[\"id\"], t[\"eval_score\"])" }, { "lang": "Bash", "label": "CLI", "source": "decimalai traces list --agent-name my-agent --limit 20" } ] } }, "/api/v1/traces/batch": { "post": { "tags": [ "traces" ], "summary": "Ingest a batch of traces", "description": "Ingest a batch of traces in a single request.\n\nEach payload follows the same shape as POST /api/v1/traces. Per-trace\nfailures are returned in the `errors` field — partial success is allowed.", "operationId": "ingest_traces_batch_api_v1_traces_batch_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Payloads" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Ingest Traces Batch Api V1 Traces Batch Post" }, "example": { "status": "ok", "count": 2, "trace_ids": [ "trc_001", "trc_002" ] } } } }, "402": { "description": "Plan trace-ingest quota exhausted." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\n# Send a batch of trace payloads (each follows the POST /api/v1/traces shape).\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/traces/batch\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n json=[trace_payload_1, trace_payload_2],\n timeout=60.0,\n)\nresp.raise_for_status()\nprint(resp.json()[\"count\"], \"ingested\")" } ] } }, "/api/v1/traces/group-by": { "get": { "tags": [ "traces" ], "summary": "Group traces by agent or session with per-group rollups", "description": "Collapse the trace list into groups (by agent or session) with summary\nmetrics per group — volume, error rate, eval pass/fail + avg score, avg\nduration, last activity. Honours the same filters as the list endpoint so a\ngroup's numbers match what `GET /traces?agent_name=` would drill into.\n\nCost/token rollups are deliberately omitted (they need a per-trace LlmCall\njoin); this view is for triage by volume/health, not billing.", "operationId": "group_traces_api_v1_traces_group_by_get", "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "enum": [ "agent", "session" ], "type": "string", "description": "Roll-up dimension: 'agent' (group by agent_name) or 'session' (group by session_id).", "default": "agent", "title": "Dimension" }, "description": "Roll-up dimension: 'agent' (group by agent_name) or 'session' (group by session_id)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "success", "error", "degraded" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "eval_verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by eval verdict, or 'unevaluated' for no verdict yet.", "title": "Eval Verdict" }, "description": "Filter by eval verdict, or 'unevaluated' for no verdict yet." }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Manifest Id" } }, { "name": "target_manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Manifest Id" } }, { "name": "compat_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compat Status" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "started_at_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At From" } }, { "name": "started_at_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At To" } }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false, drop platform-harness fixture agents from the roll-up — the UI's default. Ignored when agent_name is set.", "default": true, "title": "Include Fixtures" }, "description": "When false, drop platform-harness fixture agents from the roll-up — the UI's default. Ignored when agent_name is set." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Group Traces Api V1 Traces Group By Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/stats": { "get": { "tags": [ "traces" ], "summary": "Aggregate stats across traces", "description": "Aggregate statistics for traces matching the given filters.\n\nReturns token totals, estimated costs, latency percentiles, model\nbreakdown, and daily time-series data.", "operationId": "get_trace_stats_api_v1_traces_stats_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "source_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "include_fixtures", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false, exclude platform-harness fixture agents from the aggregates — the UI's default. Defaults to true for API back-compat. Ignored when agent_name is set.", "default": true, "title": "Include Fixtures" }, "description": "When false, exclude platform-harness fixture agents from the aggregates — the UI's default. Defaults to true for API back-compat. Ignored when agent_name is set." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Trace Stats Api V1 Traces Stats Get" }, "example": { "total_traces": 1250, "success_count": 1180, "error_count": 70, "total_input_tokens": 500000, "total_output_tokens": 250000, "total_tokens": 750000, "total_llm_calls": 3200, "total_cost_usd": 12.45, "avg_latency_ms": 1250.5, "models_used": { "gpt-4o": 2800, "claude-3-sonnet": 400 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/traces/stats\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n params={\"agent_name\": \"my-agent\"},\n)\nresp.raise_for_status()\nstats = resp.json()" }, { "lang": "Bash", "label": "CLI", "source": "decimalai traces stats --agent-name my-agent" } ] } }, "/api/v1/traces/eval/stats": { "get": { "tags": [ "traces" ], "summary": "Eval rollup stats", "description": "Aggregate evaluation statistics for the eval dashboard.\n\nReturns pass rates, score distributions, daily trends, and\nevaluator source breakdowns.\n\nGap 7 fix: When manifest_id is provided, stats are scoped to traces\nfrom that specific manifest version. This answers \"how is my CURRENT\nversion performing?\" rather than diluting metrics across all versions.", "operationId": "get_eval_stats_api_v1_traces_eval_stats_get", "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter stats to a specific manifest version", "title": "Manifest Id" }, "description": "Filter stats to a specific manifest version" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Workspace-Id" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Eval Stats Api V1 Traces Eval Stats Get" }, "example": { "total_evaluated": 500, "pass_rate": 0.87, "verdict_breakdown": { "keep": 350, "repair": 100, "drop": 50 }, "avg_quality": 0.85 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/traces/eval/stats\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n params={\"agent_name\": \"my-agent\"},\n)\nresp.raise_for_status()\nstats = resp.json()\nprint(stats[\"pass_rate\"], stats[\"verdict_breakdown\"])" } ] } }, "/api/v1/traces/{trace_id}": { "get": { "tags": [ "traces" ], "summary": "Get a trace", "description": "Get a single trace with its full span tree and LLM calls.\n\nPass `?include=eval_scores` to embed the trace's eval scores inline.\nWithout that param, the scores live at GET /traces/{id}/eval-scores\n(API-001 fix — they were previously only at the sub-endpoint).", "operationId": "get_trace_api_v1_traces__trace_id__get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated extras: eval_scores", "title": "Include" }, "description": "Comma-separated extras: eval_scores" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Trace Api V1 Traces Trace Id Get" }, "example": { "id": "trc_abc123", "agent_name": "travel-planner", "status": "success", "user_input": "Find flights to Tokyo", "final_output": "I found 3 flights to Tokyo.", "manifest_id": "mfst_001", "eval_verdict": "keep", "eval_score": 0.92, "started_at": "2026-05-10T14:22:00Z", "ended_at": "2026-05-10T14:22:01Z", "duration_ms": 1240, "total_tokens": 850, "spans": [ { "id": "s1", "name": "agent-step", "span_type": "agent", "status": "success", "started_at": "2026-05-10T14:22:00Z" } ], "llm_calls": [ { "id": "l1", "span_id": "s1", "model_name": "gpt-4o", "input_tokens": 500, "output_tokens": 350 } ] } } } }, "400": { "description": "Malformed trace_id (not a UUID)." }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.get(\n \"https://api.decimal.ai/api/v1/traces/trc_abc123\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n params={\"include\": \"eval_scores\"}, # optional\n)\nresp.raise_for_status()\ntrace = resp.json()" }, { "lang": "Bash", "label": "CLI", "source": "decimalai traces show trc_abc123" } ] } }, "/api/v1/traces/{trace_id}/export.json": { "get": { "tags": [ "traces" ], "summary": "Export a trace as a flat JSON document (audit#374 — Weave export-trace finding)", "description": "Return a self-contained JSON snapshot of the trace plus all spans + llm_calls.\n\nOrg-scoped via `trace_service.get_trace` (which honors `org_id` from `key_ctx`).\nChild trace IDs are listed so the caller can recursively expand if needed —\nwe don't inline children to keep payload size bounded and the export shape\npredictable.", "operationId": "export_trace_json_api_v1_traces__trace_id__export_json_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Export Trace Json Api V1 Traces Trace Id Export Json Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/children": { "get": { "tags": [ "traces" ], "summary": "List all child traces of a parent trace (multi-agent orchestration)", "description": "List all child traces of a parent trace (multi-agent orchestration).\n\nReturns child traces linked via parent_trace_id, ordered by started_at.", "operationId": "get_trace_children_api_v1_traces__trace_id__children_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Trace Children Api V1 Traces Trace Id Children Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/skill-rater-report": { "get": { "tags": [ "traces" ], "summary": "Get the Skill Rater report for a trace", "description": "Return the Skill Rater report for a trace, or 404 if not yet rated.\n\nSkill Rater Phase 1 (see ``platform/docs/skill_rater_and_benchmarks_design.md``).\nSkill Rater runs asynchronously after ingest on a sample of traces; this\nendpoint exposes the persisted ``SkillRaterReport`` row. A 404 means the\nRater hasn't run on this trace yet (sampling didn't pick it, cap was\nhit, or LLM call failed).\n\nThe endpoint is org-scoped: cross-tenant trace_ids return 404 to avoid\nleaking trace existence.", "operationId": "get_trace_skill_rater_report_api_v1_traces__trace_id__skill_rater_report_get", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Trace Skill Rater Report Api V1 Traces Trace Id Skill Rater Report Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/status": { "patch": { "tags": [ "traces" ], "summary": "Manually override a trace's status", "description": "Manually override a trace's status.\n\nPrimarily used to recover a parent trace from 'degraded' when the\nuser has verified that the output is correct despite child errors.\n\nBody:\n- status: \"success\" | \"error\" | \"degraded\"\n- reason: Optional explanation for the override (stored in error_message)", "operationId": "override_trace_status_api_v1_traces__trace_id__status_patch", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Override Trace Status Api V1 Traces Trace Id Status Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/evaluate": { "post": { "tags": [ "traces" ], "summary": "Run evaluators on a trace", "description": "Run evaluation on a trace.\n\nBody (optional):\n- mode: \"deterministic\" (default, free) or \"llm_judge\" (costs budget)\n- evaluator: Named evaluator to run server-side (e.g. \"relevance\",\n \"factuality\", \"toxicity\"). Requires a paid plan — no free tier.\n- context: Optional context string for RAG evaluators (factuality).", "operationId": "evaluate_trace_api_v1_traces__trace_id__evaluate_post", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "default": {}, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Evaluate Trace Api V1 Traces Trace Id Evaluate Post" }, "example": { "trace_id": "trc_abc123", "verdict": "keep", "quality_avg": 0.92, "compat_avg": 0.95, "reasons": [ "All quality checks passed." ] } } } }, "404": { "description": "Trace not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Python SDK", "source": "import httpx\n\nresp = httpx.post(\n \"https://api.decimal.ai/api/v1/traces/trc_abc123/evaluate\",\n headers={\"Authorization\": \"Bearer dai_sk_...\"},\n)\nresp.raise_for_status()\nprint(resp.json()[\"verdict\"])" } ] } }, "/api/v1/traces/{trace_id}/compatibility": { "patch": { "tags": [ "traces" ], "summary": "Set a manual compatibility override for a trace", "description": "Set a manual compatibility override for a trace.\n\nBody: {\n \"target_manifest_id\": \"...\", // required — which manifest this override applies to\n \"override_verdict\": \"keep\" | \"repair\" | \"replay\" | \"drop\" | null // null clears the override\n}\n\nFlat-trace fallback (no target manifest): {\n \"compat_status\": \"keep\" | \"repair\" | \"replay\" | \"drop\"\n}", "operationId": "update_compatibility_api_v1_traces__trace_id__compatibility_patch", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Compatibility Api V1 Traces Trace Id Compatibility Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/traces/{trace_id}/rate": { "post": { "tags": [ "traces" ], "summary": "Force-run the Skill Rater on a single trace (on-demand)", "description": "On-demand Skill Rater run for one trace — bypasses background sampling.\n\nThe Rater normally grades a sampled fraction of production traces in a\nbackground worker. This force-rates a specific trace synchronously: the\n\"Rate now\" debugging action, and the release-gate eval lane's entry point\n(the Rater otherwise has no HTTP surface). UPSERT on trace_id — re-running\noverwrites the prior report. The Rater calls Gemini; on a provider/quota\nfailure ``analyze_trace`` records an error report rather than raising, so the\ncaller gets a 200 with empty ratings + a populated ``error`` field.", "operationId": "rate_trace_api_v1_traces__trace_id__rate_post", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Rate Trace Api V1 Traces Trace Id Rate Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/providers": { "get": { "tags": [ "training" ], "summary": "List available fine-tuning providers with configuration status", "description": "List available fine-tuning providers with configuration status.", "operationId": "list_providers_api_v1_training_providers_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/credentials": { "get": { "tags": [ "training" ], "summary": "Get configured provider credentials (keys masked)", "description": "Get configured provider credentials (keys masked).", "operationId": "get_credentials_api_v1_training_credentials_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "training" ], "summary": "Store or update provider credentials", "description": "Store or update provider credentials.\n\nThe store is shared by BYOK inference (Playground, evals) and fine-tuning.\nInference only needs an api_key, so that's all we require here; Gemini's\ntraining-only fields are validated at job launch (launch_training_job).\n\nBody:\n provider: \"openai\" | \"anthropic\" | \"gemini\" | \"raw\"\n credentials: provider-specific credential object\n - openai: {\"api_key\": \"sk-...\"}\n - anthropic: {\"api_key\": \"sk-ant-...\"}\n - gemini: {\"api_key\": \"...\"} (+ optional \"project_id\", \"gcs_bucket\"\n for fine-tuning)\n - raw: {\"webhook_url\": \"https://...\"} (optional)", "operationId": "set_credentials_api_v1_training_credentials_put", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/credentials/{provider}": { "delete": { "tags": [ "training" ], "summary": "Remove stored credentials for a provider", "description": "Remove stored credentials for a provider.", "operationId": "delete_credentials_api_v1_training_credentials__provider__delete", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/jobs": { "post": { "tags": [ "training" ], "summary": "Launch a fine-tuning job", "description": "Launch a fine-tuning job.\n\nBody:\n dataset_id: ID of the dataset\n dataset_version_id: ID of the dataset version to train on\n provider: \"openai\" | \"gemini\" | \"raw\"\n base_model: model identifier (e.g. \"gpt-4o-mini-2024-07-18\")\n hyperparameters: optional dict of training config\n manifest_id: optional manifest to link the job to", "operationId": "launch_job_api_v1_training_jobs_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "training" ], "summary": "List training jobs for the org", "description": "List training jobs for the org.", "operationId": "list_jobs_api_v1_training_jobs_get", "parameters": [ { "name": "dataset_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/jobs/{job_id}": { "get": { "tags": [ "training" ], "summary": "Get training job detail with metrics", "description": "Get training job detail with metrics.", "operationId": "get_job_api_v1_training_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/jobs/{job_id}/poll": { "post": { "tags": [ "training" ], "summary": "Manually poll a training job's status from the provider.\"\"\"", "description": "Manually poll a training job's status from the provider.", "operationId": "poll_job_api_v1_training_jobs__job_id__poll_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/training/jobs/{job_id}/cancel": { "post": { "tags": [ "training" ], "summary": "Cancel a running training job", "description": "Cancel a running training job.", "operationId": "cancel_job_api_v1_training_jobs__job_id__cancel_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/multi-agent-training/{orchestrator_name}/fault-attribution": { "get": { "tags": [ "multi-agent-training" ], "summary": "Attribute orchestrator failures to sub-agents", "description": "Attribute observed orchestrator failures back to specific sub-agents.\n\nWalks failed traces under `orchestrator_name` over `window_days`\n(default 30, max 365) and assigns each failure to the sub-agent whose\nspan produced the bad output. Use this to decide which sub-agent to\ntarget for retraining.\n\nOrg-scoped: only sees traces in the caller's org.", "operationId": "fault_attribution_api_v1_multi_agent_training__orchestrator_name__fault_attribution_get", "parameters": [ { "name": "orchestrator_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Orchestrator Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/multi-agent-training/{orchestrator_name}/subagent-dataset/{subagent_name}": { "get": { "tags": [ "multi-agent-training" ], "summary": "Preview the training dataset that would be built for one sub-agent", "description": "Preview the training dataset that would be built for one sub-agent.\n\nExtracts the rows that the multi-agent training pipeline would emit\nfor `subagent_name` under `orchestrator_name`. Use this to inspect a\ncandidate dataset before launching an actual training run.\n\nFilters:\n - `window_days`: trace lookback window (default 30, max 365)\n - `limit`: max rows returned (default 50, max 500)\n - `only_passing`: when true (default), include only rows whose\n downstream verdict was a pass — i.e. positive demonstrations.\n\nReturns `{orchestrator, subagent, row_count, rows}`. Org-scoped.", "operationId": "preview_subagent_dataset_api_v1_multi_agent_training__orchestrator_name__subagent_dataset__subagent_name__get", "parameters": [ { "name": "orchestrator_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Orchestrator Name" } }, { "name": "subagent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Subagent Name" } }, { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Window Days" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "only_passing", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Only Passing" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/multi-agent-training/{orchestrator_name}/launch": { "post": { "tags": [ "multi-agent-training" ], "summary": "Fan out training jobs for N sub-agents under a single coordinator", "description": "Launch a coordinated multi-agent training run.\n\nBody:\n target_subagents: list[str] (required)\n provider: str (required, e.g. \"openai\" | \"raw\")\n base_model: str (required, e.g. \"gpt-4o-mini-2024-07-18\")\n window_days: int (default 30)\n min_rows: int (default 1)\n dry_run: bool (default false)\n hyperparameters: dict (optional)", "operationId": "launch_coordinator_api_v1_multi_agent_training__orchestrator_name__launch_post", "parameters": [ { "name": "orchestrator_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Orchestrator Name" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/multi-agent-training/coordinators/{coordinator_id}/jobs": { "get": { "tags": [ "multi-agent-training" ], "summary": "List all training jobs in a multi-agent coordinator", "description": "List the per-sub-agent training jobs fanned out by a coordinator.\n\nA multi-agent training \"coordinator\" is created by `POST\n/multi-agent-training/{orchestrator}/launch`. It fans out one\ntraining job per target sub-agent. This endpoint returns that fan-out\nso the UI can render a single coordinator row with N expandable jobs.\n\nReturns `{coordinator_id, job_count, jobs: [...]}`. Org-scoped.", "operationId": "coordinator_jobs_api_v1_multi_agent_training_coordinators__coordinator_id__jobs_get", "parameters": [ { "name": "coordinator_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Coordinator Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/stripe": { "post": { "tags": [ "webhooks" ], "summary": "Receive and process Stripe webhook events", "description": "Receive and process Stripe webhook events.\n\nVerifies the Stripe signature (HMAC-SHA256 + replay protection via\ntimestamp tolerance), then dispatches to the appropriate handler via\n`stripe_service.dispatch_event`. Returns 200 to acknowledge receipt\nso Stripe doesn't retry handler failures.\n\nNOTE: This route and `POST /api/v1/billing/webhook` share the same\ndispatcher and behave identically. Configure exactly ONE of them as\nyour Stripe webhook URL; the other is preserved for compatibility.", "operationId": "stripe_webhook_api_v1_webhooks_stripe_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeWebhookEvent" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid or missing Stripe-Signature header" }, "422": { "description": "Malformed JSON payload" } } } }, "/api/v1/webhooks/deepeval": { "post": { "tags": [ "webhooks" ], "summary": "Receive DeepEval test results via webhook", "description": "Receive DeepEval test results via webhook.\n\nExpected payload format:\n{\n \"test_results\": [\n {\n \"trace_id\": \"...\",\n \"metrics\": [\n {\"name\": \"correctness\", \"score\": 0.92, \"success\": true, \"reason\": \"...\"},\n {\"name\": \"faithfulness\", \"score\": 0.85, \"success\": true}\n ]\n }\n ]\n}\n\nVerification: X-Webhook-Secret header must match DECIMAL_DEEPEVAL_WEBHOOK_SECRET env.", "operationId": "deepeval_webhook_api_v1_webhooks_deepeval_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepEvalWebhookPayload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid or missing webhook signature" }, "422": { "description": "Malformed JSON payload" } } } }, "/api/v1/webhooks/langsmith": { "post": { "tags": [ "webhooks" ], "summary": "Receive LangSmith evaluation results via webhook", "description": "Receive LangSmith evaluation results via webhook.\n\nExpected payload format:\n{\n \"trace_id\": \"...\",\n \"scores\": [\n {\"key\": \"correctness\", \"score\": 0.9, \"comment\": \"Good response\"},\n {\"key\": \"helpfulness\", \"score\": 0.85}\n ]\n}\n\nVerification: X-Webhook-Secret header must match DECIMAL_LANGSMITH_WEBHOOK_SECRET env.", "operationId": "langsmith_webhook_api_v1_webhooks_langsmith_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LangSmithWebhookPayload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid or missing webhook signature" }, "422": { "description": "Malformed JSON payload" } } } }, "/api/v1/webhooks/clerk": { "post": { "tags": [ "webhooks" ], "summary": "Sync Clerk user events to the local User table", "description": "Sync Clerk user events to the local User table.\n\nHandles:\n- user.created → create User row\n- user.updated → update email/name/avatar\n- user.deleted → deactivate User\n\nClerk sends events with Svix signature headers. In dev mode,\nsignature verification is skipped if no secret is configured.", "operationId": "clerk_webhook_api_v1_webhooks_clerk_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClerkWebhookEvent" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid or missing Svix signature headers" }, "422": { "description": "Malformed JSON payload or unknown event type" } } } }, "/api/v1/workspaces": { "get": { "tags": [ "workspaces" ], "summary": "List workspaces visible to the current user", "description": "List workspaces visible to the current user.", "operationId": "list_workspaces_api_v1_workspaces_get", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Workspaces Api V1 Workspaces Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "workspaces" ], "summary": "Create a new workspace", "description": "Create a new workspace.", "operationId": "create_workspace_api_v1_workspaces_post", "parameters": [ { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Workspace Api V1 Workspaces Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workspaces/{workspace_id}": { "get": { "tags": [ "workspaces" ], "summary": "Get workspace details", "description": "Get workspace details.", "operationId": "get_workspace_api_v1_workspaces__workspace_id__get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Workspace Api V1 Workspaces Workspace Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "workspaces" ], "summary": "Update workspace name/description", "description": "Update workspace name/description.", "operationId": "update_workspace_api_v1_workspaces__workspace_id__patch", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Workspace Api V1 Workspaces Workspace Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "workspaces" ], "summary": "Delete a workspace (cannot delete default)", "description": "Delete a workspace (cannot delete default).", "operationId": "delete_workspace_api_v1_workspaces__workspace_id__delete", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Delete Workspace Api V1 Workspaces Workspace Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workspaces/{workspace_id}/members": { "get": { "tags": [ "workspaces" ], "summary": "List members of a workspace", "description": "List members of a workspace.", "operationId": "list_workspace_members_api_v1_workspaces__workspace_id__members_get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Workspace Members Api V1 Workspaces Workspace Id Members Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "workspaces" ], "summary": "Add a user to a workspace", "description": "Add a user to a workspace.\n\nBody: {\"user_id\": \"...\", \"role\": \"editor\"}\nor: {\"email\": \"...\", \"role\": \"editor\"}", "operationId": "add_workspace_member_api_v1_workspaces__workspace_id__members_post", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Add Workspace Member Api V1 Workspaces Workspace Id Members Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workspaces/{workspace_id}/members/{user_id}": { "delete": { "tags": [ "workspaces" ], "summary": "Remove a user from a workspace", "description": "Remove a user from a workspace.", "operationId": "remove_workspace_member_api_v1_workspaces__workspace_id__members__user_id__delete", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Remove Workspace Member Api V1 Workspaces Workspace Id Members User Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "workspaces" ], "summary": "Update a workspace member's role", "description": "Update a workspace member's role.\n\nOnly workspace admins can change roles.\nBody: {\"role\": \"editor\" | \"viewer\" | \"admin\"}", "operationId": "update_workspace_member_role_api_v1_workspaces__workspace_id__members__user_id__patch", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "decimal_session", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decimal Session" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Update Workspace Member Role Api V1 Workspaces Workspace Id Members User Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ApplyRepairRequest": { "properties": { "old_manifest_id": { "type": "string", "title": "Old Manifest Id" }, "new_manifest_id": { "type": "string", "title": "New Manifest Id" } }, "type": "object", "required": [ "old_manifest_id", "new_manifest_id" ], "title": "ApplyRepairRequest", "description": "Body for `POST /repair/apply`." }, "ApplySelectiveRepairRequest": { "properties": { "old_manifest_id": { "type": "string", "title": "Old Manifest Id" }, "new_manifest_id": { "type": "string", "title": "New Manifest Id" }, "approved_rule_indices": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "Approved Rule Indices", "description": "Indices (from /preview's rules array) of the rules to apply" } }, "type": "object", "required": [ "old_manifest_id", "new_manifest_id", "approved_rule_indices" ], "title": "ApplySelectiveRepairRequest", "description": "Body for `POST /repair/apply-selective`." }, "BatchDecisionRequest": { "properties": { "trace_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trace Ids", "description": "Specific trace IDs to score" }, "manifest_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Manifest Id", "description": "Score all traces from this manifest" } }, "type": "object", "title": "BatchDecisionRequest", "description": "Request for batch verdict computation." }, "BatchDecisionResponse": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/DecisionResponse" }, "type": "array", "title": "Decisions" }, "total": { "type": "integer", "title": "Total" }, "verdict_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Verdict Counts" } }, "type": "object", "required": [ "decisions", "total", "verdict_counts" ], "title": "BatchDecisionResponse", "description": "Response from batch verdict computation." }, "Body_import_jsonl_api_v1_import_jsonl_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, "type": "object", "required": [ "file" ], "title": "Body_import_jsonl_api_v1_import_jsonl_post" }, "Body_import_jsonl_api_v1_traces_import_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, "type": "object", "required": [ "file" ], "title": "Body_import_jsonl_api_v1_traces_import_post" }, "BulkCreateAttachmentRequest": { "properties": { "files": { "items": { "$ref": "#/components/schemas/CreateAttachmentRequest" }, "type": "array", "title": "Files", "description": "List of files to create" } }, "type": "object", "required": [ "files" ], "title": "BulkCreateAttachmentRequest", "description": "Request to create multiple attachments at once." }, "CreateAnnotationRequest": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "thumbs_up | thumbs_down | needs_correction (legacy, auto-derived if omitted)" }, "rating": { "anyOf": [ { "type": "integer", "maximum": 5, "minimum": 1 }, { "type": "null" } ], "title": "Rating", "description": "1-5 star quality rating" }, "correctness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correctness", "description": "correct | partial | incorrect" }, "error_categories": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Error Categories", "description": "e.g. [\"hallucination\", \"missing_info\"]" }, "corrected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Corrected Output" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "score": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Score" }, "flagged_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Flagged For Review", "default": false }, "add_to_dataset": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Add To Dataset", "default": false } }, "additionalProperties": false, "type": "object", "title": "CreateAnnotationRequest" }, "CreateAttachmentRequest": { "properties": { "file_path": { "type": "string", "title": "File Path", "description": "Relative path, e.g. 'scripts/validate.py'" }, "directory": { "type": "string", "title": "Directory", "description": "One of: scripts, references, templates, assets" }, "content_text": { "type": "string", "title": "Content Text", "description": "File content as text" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type", "description": "MIME type (auto-detected if omitted)" }, "skill_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Version Id", "description": "Version scope (null = shared)" } }, "type": "object", "required": [ "file_path", "directory", "content_text" ], "title": "CreateAttachmentRequest", "description": "Request to create a single skill attachment." }, "CreateSkillRequest": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "URL-safe slug. Lowercase alphanumeric with hyphens/underscores/dots.", "examples": [ "search-flights" ] }, "description": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Description", "description": "Short one-line description shown in the skill registry.", "examples": [ "Search available flights given origin, destination, and dates." ] }, "body_markdown": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Body Markdown", "description": "Full SKILL.md body. At least 50 characters of substantive content." }, "body": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Body", "description": "Alias for body_markdown — accepted for backwards compatibility." }, "visibility": { "type": "string", "title": "Visibility", "description": "One of: org, workspace, personal, public.", "default": "org", "examples": [ "org" ] }, "stability": { "type": "string", "title": "Stability", "description": "One of: stable, experimental, deprecated.", "default": "stable", "examples": [ "stable" ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Category", "description": "Optional grouping label, e.g. 'tools', 'policies', 'workflows'.", "examples": [ "tools" ] }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases", "description": "Phrases that hint the skill should activate. Used by smart routing.", "examples": [ [ "find flights", "search for flights" ] ] }, "frontmatter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Frontmatter", "description": "Raw frontmatter dict parsed from the SKILL.md header." }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary", "description": "Optional message attached to the first version." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author", "description": "Optional author label for the first version." }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id", "description": "Scope the skill to a specific project." }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "Owning workspace ID. Defaults to the caller's current workspace." } }, "type": "object", "required": [ "name", "description" ], "title": "CreateSkillRequest", "description": "Validated request for POST /skills.\n\nUses relaxed name validation (allows underscores, dots, up to 200 chars)." }, "CreateSkillResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "skill_id": { "type": "string", "title": "Skill Id", "description": "Stable ID, always prefixed 'sk_'" }, "name": { "type": "string", "title": "Name" }, "version": { "type": "integer", "title": "Version", "description": "Starts at 1; increments on each body change" } }, "type": "object", "required": [ "status", "skill_id", "name", "version" ], "title": "CreateSkillResponse" }, "DecisionPayload": { "properties": { "decision": { "anyOf": [ { "type": "string", "enum": [ "intentional", "acknowledged", "needs_review" ] }, { "type": "null" } ], "title": "Decision", "description": "Engineer's human annotation. null clears any prior decision; intentional/acknowledged/needs_review record one." } }, "additionalProperties": false, "type": "object", "title": "DecisionPayload", "description": "H1095 (improve#673): typed body for the decision endpoint.\n\nPre-fix the handler took ``Dict[str, Any]`` and read only the ``decision``\nkey, so ``{\"action\": \"approve\"}`` (the persona's typo of the field name)\nwas silently treated as ``{\"decision\": None}`` — clearing any prior\ndecision rather than recording one. The HIGH-severity flag on this item\nis because the broken-decision-flow runs underneath the regression-check\nUI's \"Approve\" button.\n\nFix: typed body with ``extra='forbid'`` so unknown keys 422 + Literal\nenum on ``decision`` so unknown values also 422 (replaces the inline\n``if decision not in ...`` check below)." }, "DecisionResponse": { "properties": { "trace_id": { "type": "string", "title": "Trace Id" }, "verdict": { "type": "string", "title": "Verdict" }, "quality_avg": { "type": "number", "title": "Quality Avg" }, "compat_avg": { "type": "number", "title": "Compat Avg" }, "quality_scores": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Quality Scores" }, "compat_scores": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Compat Scores" }, "reasons": { "items": { "type": "string" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "trace_id", "verdict", "quality_avg", "compat_avg", "quality_scores", "compat_scores", "reasons" ], "title": "DecisionResponse", "description": "Response from the decision engine." }, "DeleteSkillResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "deleted": { "type": "boolean", "title": "Deleted" } }, "type": "object", "required": [ "status", "deleted" ], "title": "DeleteSkillResponse" }, "EvalBreakdownResponse": { "properties": { "trace_id": { "type": "string", "title": "Trace Id" }, "eval_verdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eval Verdict" }, "quality_avg": { "type": "number", "title": "Quality Avg" }, "compat_avg": { "type": "number", "title": "Compat Avg" }, "quality_scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Quality Scores" }, "compat_scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Compat Scores" }, "source_groups": { "items": { "$ref": "#/components/schemas/SourceGroup" }, "type": "array", "title": "Source Groups" }, "decision_reasons": { "items": { "type": "string" }, "type": "array", "title": "Decision Reasons" } }, "type": "object", "required": [ "trace_id", "quality_avg", "compat_avg", "quality_scores", "compat_scores", "source_groups", "decision_reasons" ], "title": "EvalBreakdownResponse", "description": "Full eval breakdown with provenance, for trace detail page." }, "ForkSkillRequest": { "properties": { "new_name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "New Name" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, "type": "object", "required": [ "new_name" ], "title": "ForkSkillRequest", "description": "Validated request for POST /skills/{name}/fork." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InstallSkillState": { "properties": { "skill_id": { "type": "string", "title": "Skill Id" }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name" }, "status": { "type": "string", "title": "Status", "description": "in_sync | local_ahead | remote_ahead | conflict | local_only | unknown" }, "local_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Hash" }, "remote_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Remote Hash" }, "synced_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Synced Hash" }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Synced At" }, "last_reported_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Reported At" } }, "type": "object", "required": [ "skill_id", "status" ], "title": "InstallSkillState", "description": "One skill's divergence within an install." }, "InstallState": { "properties": { "install_id": { "type": "string", "title": "Install Id" }, "install_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Install Label" }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Synced At" }, "last_reported_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Reported At" }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Counts", "description": "status → count rollup for the bar." }, "skills": { "items": { "$ref": "#/components/schemas/InstallSkillState" }, "type": "array", "title": "Skills" } }, "type": "object", "required": [ "install_id", "counts", "skills" ], "title": "InstallState", "description": "One install's view of its skills." }, "ListInstallsResponse": { "properties": { "installs": { "items": { "$ref": "#/components/schemas/InstallState" }, "type": "array", "title": "Installs" } }, "type": "object", "required": [ "installs" ], "title": "ListInstallsResponse" }, "ListScoresResponse": { "properties": { "trace_id": { "type": "string", "title": "Trace Id" }, "quality_scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Quality Scores" }, "compatibility_scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Compatibility Scores" }, "aggregate_quality": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Aggregate Quality" }, "aggregate_compatibility": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Aggregate Compatibility" } }, "type": "object", "required": [ "trace_id", "quality_scores", "compatibility_scores" ], "title": "ListScoresResponse", "description": "Response for listing scores on a trace." }, "ListSkillsResponse": { "properties": { "skills": { "items": { "$ref": "#/components/schemas/SkillSummary" }, "type": "array", "title": "Skills" }, "total": { "type": "integer", "title": "Total", "description": "Total skills visible to the caller, after visibility filtering" } }, "type": "object", "required": [ "skills", "total" ], "title": "ListSkillsResponse" }, "ListVersionsResponse": { "properties": { "skill_name": { "type": "string", "title": "Skill Name" }, "versions": { "items": { "$ref": "#/components/schemas/SkillVersionDetail" }, "type": "array", "title": "Versions" } }, "type": "object", "required": [ "skill_name", "versions" ], "title": "ListVersionsResponse" }, "PlaygroundCompareRequest": { "properties": { "user_input": { "type": "string", "title": "User Input", "default": "" }, "baseline_output": { "type": "string", "title": "Baseline Output" }, "candidate_output": { "type": "string", "title": "Candidate Output" }, "change_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Context" }, "model": { "type": "string", "title": "Model" }, "provider_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Hint", "default": "" } }, "type": "object", "required": [ "baseline_output", "candidate_output", "model" ], "title": "PlaygroundCompareRequest", "description": "Request a relative pairwise verdict for two outputs on the same input.\n\nThe judge runs on the USER's BYOK key (the same provider/model they're\ntesting) — never a platform key — so a Playground verdict can't be blocked\nby, or billed to, DecimalAI's LLM quota." }, "PlaygroundRunRequest": { "properties": { "messages": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Messages" }, "model": { "type": "string", "title": "Model" }, "provider_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Hint", "default": "" }, "temperature": { "type": "number", "title": "Temperature", "default": 0.7 }, "original_trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Trace Id" } }, "type": "object", "required": [ "messages", "model" ], "title": "PlaygroundRunRequest", "description": "Request to execute a modified LLM call." }, "PreviewRepairRequest": { "properties": { "old_manifest_id": { "type": "string", "title": "Old Manifest Id", "description": "Manifest the traces were captured against" }, "new_manifest_id": { "type": "string", "title": "New Manifest Id", "description": "Manifest to migrate the traces to" }, "sample_size": { "type": "integer", "maximum": 50, "minimum": 1, "title": "Sample Size", "description": "How many traces to preview", "default": 5 } }, "type": "object", "required": [ "old_manifest_id", "new_manifest_id" ], "title": "PreviewRepairRequest", "description": "Body for `POST /repair/preview`." }, "PromoteRequest": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" }, "label_filter": { "type": "string", "title": "Label Filter", "default": "thumbs_up" }, "limit": { "type": "integer", "maximum": 5000, "minimum": 1, "title": "Limit", "default": 500 } }, "type": "object", "title": "PromoteRequest" }, "PushScoresRequest": { "properties": { "source": { "type": "string", "title": "Source", "description": "Source system: 'custom', 'my-pipeline', etc. (reserved external-tool names like 'deepeval' require the webhook path)" }, "scores": { "items": { "$ref": "#/components/schemas/ScoreInput" }, "type": "array", "minItems": 1, "title": "Scores", "description": "List of scores to push" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Source-specific metadata (run_id, metric version, etc.)" } }, "type": "object", "required": [ "source", "scores" ], "title": "PushScoresRequest", "description": "Request body for pushing external eval scores." }, "PushScoresResponse": { "properties": { "trace_id": { "type": "string", "title": "Trace Id" }, "source": { "type": "string", "title": "Source" }, "scores_stored": { "type": "integer", "title": "Scores Stored" }, "scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Scores" } }, "type": "object", "required": [ "trace_id", "source", "scores_stored", "scores" ], "title": "PushScoresResponse", "description": "Response after pushing scores." }, "RegistryImportItem": { "properties": { "source": { "type": "string", "title": "Source", "description": "'github' (fetch from URL) or 'platform' (inline body)" }, "github_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Github Url", "description": "GitHub URL to SKILL.md (blob format)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Skill name (required for platform, auto-detected for GitHub)" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Skill description" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown", "description": "Full skill body (required for platform source)" }, "category": { "type": "string", "title": "Category", "description": "Registry category (e.g. 'code-review', 'testing')", "default": "general" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Registry tags" }, "badge": { "type": "string", "title": "Badge", "description": "Registry badge: verified, featured, community, imported", "default": "community" }, "author_display_name": { "type": "string", "title": "Author Display Name", "description": "Author display name in registry", "default": "Community" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "SPDX license identifier" }, "compatibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compatibility", "description": "Environment requirements" }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "description": "Pre-approved tools list" }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases", "description": "Keyword hints for routing" } }, "type": "object", "required": [ "source" ], "title": "RegistryImportItem", "description": "A single skill to import into the public registry." }, "RegistryImportRequest": { "properties": { "skills": { "items": { "$ref": "#/components/schemas/RegistryImportItem" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Skills" } }, "type": "object", "required": [ "skills" ], "title": "RegistryImportRequest", "description": "Batch import request." }, "RenameSkillRequest": { "properties": { "new_name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "New Name" } }, "type": "object", "required": [ "new_name" ], "title": "RenameSkillRequest", "description": "Validated request for POST /skills/{id}/rename.\n\n2026-06-01 — added to support publish-with-rename in PublishDialog.\nA user wants to publish a fork under a public name different from\ntheir local name; the dialog renames the local skill first, then\npublishes under the new name. Validation only enforces length here;\norg-uniqueness is checked in the service layer where the org_id is\navailable." }, "RenameSkillResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "skill_id": { "type": "string", "title": "Skill Id" }, "old_name": { "type": "string", "title": "Old Name" }, "new_name": { "type": "string", "title": "New Name" } }, "type": "object", "required": [ "status", "skill_id", "old_name", "new_name" ], "title": "RenameSkillResponse" }, "ReportInstallItem": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Name" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Hash", "description": "The install's local SHA-256 of the SKILL.md body (16-hex or full)." } }, "type": "object", "required": [ "name" ], "title": "ReportInstallItem", "description": "One skill an install is reporting the local hash of.\n\nStrict name validation (agentskills.io spec), same as the sync path.\n``content_hash`` is the install's locally-computed body hash; omitting it\n(or sending blank) reports the skill as having no observable local copy." }, "ReportInstallRequest": { "properties": { "install_id": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Install Id" }, "install_label": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Install Label" }, "skills": { "items": { "$ref": "#/components/schemas/ReportInstallItem" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Skills" } }, "type": "object", "required": [ "install_id", "skills" ], "title": "ReportInstallRequest", "description": "Validated request for POST /skills/installs/report.\n\nRead-only with respect to skills/versions: it never creates or mutates a\nskill — it only refreshes the (org, install, skill) divergence row's\nlocally-observed hash. Powers a future `decimalai skills status` that shows\ndrift pills without pushing anything." }, "ReportInstallResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "install_id": { "type": "string", "title": "Install Id" }, "skills": { "items": { "$ref": "#/components/schemas/ReportInstallSkillResult" }, "type": "array", "title": "Skills" } }, "type": "object", "required": [ "status", "install_id", "skills" ], "title": "ReportInstallResponse" }, "ReportInstallSkillResult": { "properties": { "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status" }, "local_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Hash" }, "remote_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Remote Hash" } }, "type": "object", "required": [ "name", "status" ], "title": "ReportInstallSkillResult" }, "ScoreInput": { "properties": { "name": { "type": "string", "maxLength": 255, "title": "Name", "description": "Metric name, e.g. 'correctness', 'faithfulness'" }, "score": { "type": "number", "maximum": 1, "minimum": 0, "title": "Score", "description": "Score value 0.0–1.0" }, "passed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Passed", "description": "Binary pass/fail. Auto-derived from score >= 0.5 if omitted" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Human-readable explanation" } }, "type": "object", "required": [ "name", "score" ], "title": "ScoreInput", "description": "A single evaluation score." }, "ScoreResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "score": { "type": "number", "title": "Score" }, "passed": { "type": "boolean", "title": "Passed" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "source": { "type": "string", "title": "Source" }, "source_label": { "type": "string", "title": "Source Label", "default": "" }, "icon": { "type": "string", "title": "Icon", "default": "" }, "badge_color": { "type": "string", "title": "Badge Color", "default": "" }, "category": { "type": "string", "title": "Category" }, "change_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Type" }, "field_changes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Field Changes" } }, "type": "object", "required": [ "id", "name", "score", "passed", "source", "category" ], "title": "ScoreResponse", "description": "A single stored score in the response, with provenance." }, "SkillAgent": { "properties": { "agent_name": { "type": "string", "title": "Agent Name" }, "activation_count": { "type": "integer", "title": "Activation Count" } }, "type": "object", "required": [ "agent_name", "activation_count" ], "title": "SkillAgent" }, "SkillDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "stability": { "type": "string", "title": "Stability" }, "is_active": { "type": "boolean", "title": "Is Active" }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases" }, "embedding_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embedding Model" }, "embedding_dimensions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Embedding Dimensions" }, "latest_version": { "anyOf": [ { "$ref": "#/components/schemas/SkillVersionInfo" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License" }, "license_spdx": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Spdx" }, "compatibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compatibility" }, "allowed_tools": { "items": { "type": "string" }, "type": "array", "title": "Allowed Tools" }, "privacy_statement_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Privacy Statement Url" }, "data_handling_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data Handling Summary" }, "safety_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Safety Status" }, "safety": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Safety" }, "safety_scan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Safety Scan" }, "intent_review": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Intent Review" }, "content_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Status" }, "content_review": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content Review" }, "last_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated At", "description": "last_synced_at for imported skills, else created_at" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/SkillOwner" }, { "type": "null" } ] }, "visibility": { "type": "string", "title": "Visibility" }, "can_edit": { "type": "boolean", "title": "Can Edit" }, "can_share": { "type": "boolean", "title": "Can Share", "description": "Stricter than can_edit; required to publish or transfer" }, "forked_from_skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forked From Skill Id" }, "activation_count": { "type": "integer", "title": "Activation Count", "default": 0 }, "effectiveness_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Effectiveness Score" }, "pass_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Pass Rate" }, "success_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Success Rate" }, "trend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trend" } }, "type": "object", "required": [ "id", "name", "stability", "is_active", "visibility", "can_edit", "can_share" ], "title": "SkillDetail", "description": "Full skill record returned by GET /api/v1/skills/{skill_name}." }, "SkillOwner": { "properties": { "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "workspace_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Name" } }, "type": "object", "title": "SkillOwner" }, "SkillSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "stability": { "type": "string", "title": "Stability", "description": "One of: stable, experimental, deprecated" }, "is_active": { "type": "boolean", "title": "Is Active" }, "visibility": { "type": "string", "title": "Visibility", "description": "One of: org, workspace, personal, public" }, "latest_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Version Id" }, "latest_version": { "anyOf": [ { "$ref": "#/components/schemas/SkillVersionInfo" }, { "type": "null" } ] }, "embedding_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embedding Model" }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases" }, "activation_count": { "type": "integer", "title": "Activation Count", "default": 0 }, "agents": { "items": { "$ref": "#/components/schemas/SkillAgent" }, "type": "array", "title": "Agents", "default": [] }, "agent_count": { "type": "integer", "title": "Agent Count", "default": 0 }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/SkillOwner" }, { "type": "null" } ] }, "can_edit": { "type": "boolean", "title": "Can Edit" }, "subscriber_count": { "type": "integer", "title": "Subscriber Count", "default": 0 }, "effectiveness_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Effectiveness Score" }, "pass_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Pass Rate" }, "success_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Success Rate" }, "trend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trend" }, "sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sync Status" }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Synced At" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type", "default": "platform" }, "forked_from_skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forked From Skill Id" }, "forked_at_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forked At Version Id" }, "has_upstream_update": { "type": "boolean", "title": "Has Upstream Update", "default": false }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "name", "stability", "is_active", "visibility", "can_edit" ], "title": "SkillSummary", "description": "Skill row returned inside ListSkillsResponse.skills." }, "SkillVersionDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "version_number": { "type": "integer", "title": "Version Number" }, "content_hash": { "type": "string", "title": "Content Hash" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "version_number", "content_hash" ], "title": "SkillVersionDetail" }, "SkillVersionInfo": { "properties": { "version_number": { "type": "integer", "title": "Version Number" }, "content_hash": { "type": "string", "title": "Content Hash", "description": "SHA-256 of the body markdown, first 16 hex chars" }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "ISO 8601 timestamp" } }, "type": "object", "required": [ "version_number", "content_hash" ], "title": "SkillVersionInfo" }, "SourceGroup": { "properties": { "source": { "type": "string", "title": "Source" }, "source_label": { "type": "string", "title": "Source Label" }, "icon": { "type": "string", "title": "Icon" }, "badge_color": { "type": "string", "title": "Badge Color" }, "category": { "type": "string", "title": "Category" }, "scores": { "items": { "$ref": "#/components/schemas/ScoreResponse" }, "type": "array", "title": "Scores" }, "source_avg": { "type": "number", "title": "Source Avg" } }, "type": "object", "required": [ "source", "source_label", "icon", "badge_color", "category", "scores", "source_avg" ], "title": "SourceGroup", "description": "Scores grouped by source for display." }, "SyncSkillAction": { "properties": { "name": { "type": "string", "title": "Name" }, "action": { "type": "string", "enum": [ "created", "pushed", "pulled", "no_change", "failed" ], "title": "Action" }, "new_version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "New Version Number" }, "new_content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Content Hash" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version Number" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Hash" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "name", "action" ], "title": "SyncSkillAction", "description": "One entry in the `actions` list returned in `response_mode='diff'`.\n\nAction values:\n - `created`: skill didn't exist on backend; freshly registered.\n - `pushed`: remote already had it; local body differed and was newer\n (or `conflict_policy='local_wins'` forced the push). Backend version\n bumped.\n - `pulled`: remote was newer (or `conflict_policy='remote_wins'`); the\n full `body_markdown` is returned so the caller can overwrite local.\n - `no_change`: content_hash matched; nothing to do.\n - `failed`: per-skill error (e.g. invalid name caught after validation)." }, "SyncSkillItem": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Name" }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Display Name" }, "description": { "type": "string", "maxLength": 1024, "title": "Description", "default": "" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "category": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Category" }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases" }, "frontmatter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Frontmatter" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Hash", "description": "Optional SHA-256 of body_markdown; computed server-side if omitted." }, "local_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Updated At", "description": "ISO-8601 timestamp of the local file's last mtime (for newer_wins)." }, "eval_yaml_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eval Yaml Text", "description": "Optional eval.yaml co-sync — publisher's benchmark suite alongside SKILL.md." }, "eval_yaml_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eval Yaml Hash", "description": "Optional SHA-256 of eval_yaml_text (clients may pre-compute for parity with content_hash)." }, "attachments": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Attachments", "description": "Optional bundled files keyed by bundle-relative path (e.g. 'references/icd10cm.json', 'scripts/checksum.py'); the leading segment must be a valid attachment directory. Mirrored into version-scoped SkillAttachments so the benchmark sandbox can materialize them — lets a publisher carry references/ over the wire the way the disk loader does. Text-only; capped server-side (count/size/path-depth)." } }, "type": "object", "required": [ "name" ], "title": "SyncSkillItem", "description": "One item in the POST /skills/sync skills array.\n\nStrict name validation (agentskills.io spec: a-z, digits, hyphens only,\n1-64 chars). Description and body are more lenient since the SDK\nauto-generates them. Optional `content_hash` lets clients that have\nalready hashed the body (CLI walking a directory) skip the server-side\nSHA-256 — backend computes it when omitted.\n\nOptional `local_updated_at` feeds the `conflict_policy=\"newer_wins\"`\ndecision when remote and local diverge." }, "SyncSkillsRequest": { "properties": { "skills": { "items": { "$ref": "#/components/schemas/SyncSkillItem" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Skills" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author", "description": "Author display name recorded on every SkillVersion created by this sync." }, "install_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Install Id", "description": "Project-local install identity (persisted by the SDK in .decimal/install.json). When present, the sync records per-install divergence state so `GET /skills/installs` can flag local/remote drift. Omit for back-compat: the sync then behaves exactly as before." }, "install_label": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Install Label", "description": "Human-friendly install label (hostname, 'ci', …) for the dashboard." }, "conflict_policy": { "type": "string", "enum": [ "newer_wins", "local_wins", "remote_wins" ], "title": "Conflict Policy", "description": "newer_wins: compare timestamps (default; right for interactive CLI). local_wins: always overwrite remote (right for CI / build artifacts). remote_wins: never overwrite local; conflicts return `pulled` actions.", "default": "newer_wins" }, "response_mode": { "type": "string", "enum": [ "summary", "diff" ], "title": "Response Mode", "description": "summary: return counts only (cheap; SDK default). diff: return per-skill `actions` array including bodies for pulled skills (CLI).", "default": "summary" } }, "type": "object", "required": [ "skills" ], "title": "SyncSkillsRequest", "description": "Validated request for POST /skills/sync.\n\nSingle endpoint covers both CLI (bidirectional reconciliation) and SDK\n(one-way upsert) — the difference is the `response_mode` flag (rich\n`actions` array for CLI, summary counts for SDK) and the `conflict_policy`\n(CLI defaults to `newer_wins` for human-in-the-loop, CI/SDK should set\n`local_wins` because the repo is the source of truth)." }, "SyncSkillsResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "created": { "type": "integer", "title": "Created", "description": "Number of new skills created." }, "updated": { "type": "integer", "title": "Updated", "description": "Number of existing skills with a new version (pushed)." }, "unchanged": { "type": "integer", "title": "Unchanged", "description": "Number of skills whose body hash matched — no-op." }, "pulled": { "type": "integer", "title": "Pulled", "description": "Number of skills where remote was newer; caller should refresh local.", "default": 0 }, "failures": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Failures", "description": "Per-skill failures with name + error." }, "actions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SyncSkillAction" }, "type": "array" }, { "type": "null" } ], "title": "Actions", "description": "Per-skill action list — present only when `response_mode='diff'`." } }, "type": "object", "required": [ "status", "created", "updated", "unchanged" ], "title": "SyncSkillsResponse" }, "UpdateAnnotationRequest": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "rating": { "anyOf": [ { "type": "integer", "maximum": 5, "minimum": 1 }, { "type": "null" } ], "title": "Rating" }, "correctness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correctness" }, "error_categories": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Error Categories" }, "corrected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Corrected Output" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "score": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Score" }, "flagged_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Flagged For Review" }, "add_to_dataset": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Add To Dataset" } }, "type": "object", "title": "UpdateAnnotationRequest" }, "UpdateAttachmentRequest": { "properties": { "content_text": { "type": "string", "title": "Content Text", "description": "New file content as text" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type", "description": "MIME type (kept if omitted)" }, "is_executable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Executable", "description": "Override executability flag" }, "execution_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Language", "description": "Override execution language" } }, "type": "object", "required": [ "content_text" ], "title": "UpdateAttachmentRequest", "description": "Request to overwrite an existing attachment's content (PUT)." }, "UpdateSkillRequest": { "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Description" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "stability": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stability" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "category": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Category" }, "trigger_phrases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Trigger Phrases" }, "frontmatter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Frontmatter" }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" } }, "type": "object", "title": "UpdateSkillRequest", "description": "Validated request for PUT /skills/{id}.\n\nAll fields optional (partial update)." }, "UpdateSkillResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status" }, "skill_id": { "type": "string", "title": "Skill Id" }, "name": { "type": "string", "title": "Name" }, "latest_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Version Id", "description": "ID of the new version if body changed; unchanged otherwise." } }, "type": "object", "required": [ "status", "skill_id", "name" ], "title": "UpdateSkillResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "_TestCaseBody": { "properties": { "name": { "type": "string", "maxLength": 200, "title": "Name" }, "prompt": { "type": "string", "title": "Prompt" }, "expectations": { "items": { "type": "string" }, "type": "array", "title": "Expectations" }, "setup": { "items": { "type": "string" }, "type": "array", "title": "Setup" }, "validators": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Validators" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode" }, "user_goal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Goal" }, "max_turns": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Turns" }, "environment": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Environment" }, "simulator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Simulator" }, "policy_check": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Policy Check" }, "trials": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trials" } }, "type": "object", "required": [ "name", "prompt" ], "title": "_TestCaseBody" }, "StripeWebhookEvent": { "description": "Stripe webhook event envelope.\n\nhttps://stripe.com/docs/api/events/object — abbreviated to the\nfields DecimalAI actually inspects.", "properties": { "id": { "description": "Stripe event ID (evt_*)", "title": "Id", "type": "string" }, "type": { "description": "e.g., \"customer.subscription.updated\"", "title": "Type", "type": "string" }, "livemode": { "default": false, "title": "Livemode", "type": "boolean" }, "created": { "description": "Unix epoch seconds", "title": "Created", "type": "integer" }, "data": { "additionalProperties": true, "description": "`{\"object\": {...}}` payload", "title": "Data", "type": "object" } }, "required": [ "id", "type", "created", "data" ], "title": "StripeWebhookEvent", "type": "object" }, "DeepEvalMetric": { "properties": { "name": { "title": "Name", "type": "string" }, "score": { "title": "Score", "type": "number" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Success" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" } }, "required": [ "name", "score" ], "title": "DeepEvalMetric", "type": "object" }, "DeepEvalTestResult": { "properties": { "trace_id": { "title": "Trace Id", "type": "string" }, "metrics": { "items": { "$ref": "#/components/schemas/DeepEvalMetric" }, "title": "Metrics", "type": "array" } }, "required": [ "trace_id", "metrics" ], "title": "DeepEvalTestResult", "type": "object" }, "DeepEvalWebhookPayload": { "description": "Payload shape for POST /api/v1/webhooks/deepeval.", "properties": { "test_results": { "items": { "$ref": "#/components/schemas/DeepEvalTestResult" }, "title": "Test Results", "type": "array" } }, "required": [ "test_results" ], "title": "DeepEvalWebhookPayload", "type": "object" }, "LangSmithFeedback": { "properties": { "key": { "description": "Feedback name, e.g., \"correctness\"", "title": "Key", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Score" }, "value": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Value" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Comment" } }, "required": [ "key" ], "title": "LangSmithFeedback", "type": "object" }, "LangSmithWebhookPayload": { "description": "Payload shape for POST /api/v1/webhooks/langsmith.", "properties": { "run_id": { "description": "LangSmith run ID (UUID)", "title": "Run Id", "type": "string" }, "feedback": { "items": { "$ref": "#/components/schemas/LangSmithFeedback" }, "title": "Feedback", "type": "array" } }, "required": [ "run_id", "feedback" ], "title": "LangSmithWebhookPayload", "type": "object" }, "ClerkWebhookEvent": { "description": "Clerk webhook event envelope.\n\nhttps://clerk.com/docs/integrations/webhooks", "properties": { "type": { "description": "e.g., \"user.created\", \"organization.deleted\"", "title": "Type", "type": "string" }, "data": { "additionalProperties": true, "title": "Data", "type": "object" }, "object": { "default": "event", "description": "Always \"event\" for webhook deliveries", "title": "Object", "type": "string" } }, "required": [ "type", "data" ], "title": "ClerkWebhookEvent", "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Enter your API key (e.g. dai_sk_test_key_001)" } } }, "tags": [ { "name": "traces", "description": "Ingest, search, and inspect agent execution traces. A trace is the atomic unit of the platform — every other feature (evaluation, compatibility scoring, dataset building) operates on traces. Each trace is auto-tagged with the manifest hash of the agent that produced it." }, { "name": "eval-scores", "description": "Push, fetch, and aggregate per-trace evaluation scores. Scores carry source provenance (built-in, DeepEval, LangSmith, custom) and feed the unified decision engine, which produces a keep / repair / replay / drop verdict per trace." }, { "name": "skills", "description": "Manage reusable instruction blocks (SKILL.md files) that modify agent behavior. Skills are first-class manifest components — changes to a skill appear in your regression-check impact reports. Use these endpoints to create, version, fork, and sync skills with your local SKILL.md files." }, { "name": "manifests", "description": "Register and inspect manifest versions. A manifest is a snapshot of your agent's structural identity (tools, prompts, models, skills) at a point in time. The SDK registers manifests automatically; these endpoints expose the underlying records." }, { "name": "datasets", "description": "Build versioned SFT/DPO training datasets from manifest-classified, eval-scored traces. Datasets are reproducible — each version locks the manifest and filter set used to build it. Export as JSONL, Parquet, or push to HuggingFace Hub." }, { "name": "replay", "description": "Re-execute historical traces against a new manifest version. Replay is the deferred-future capability for behavioral verification of agent changes. The SDK creates a replay batch, your worker executes each task, then submits results back here for eval scoring." }, { "name": "registry", "description": "Browse and install community skills from the public skills registry. Each registry skill carries a SkillScore — an evidence-tiered quality composite computed from real-world evals, benchmarks, and ratings across organizations. Installing creates a fork in your org — edits don't affect the public version." }, { "name": "agents", "description": "List and inspect agents, plus their multi-agent topology (orchestrator → sub-agent edges discovered from traces). Agents are identified by a stable agent_name string set in your SDK init() call." }, { "name": "import", "description": "Bulk-import historical traces from another observability platform or a JSONL backup. Useful for migrating from LangSmith / Braintrust / Langfuse. Duplicate trace IDs are silently skipped — re-running an import is safe." } ], "security": [ { "BearerAuth": [] } ] }