{
  "openapi": "3.1.0",
  "info": {
    "title": "Qurator Assurance API",
    "version": "0.3.0",
    "description": "Public Freemium/Paid `/evaluate` and `/v1/assure/*` surface (D-073). Authenticate with a Bearer API key from Studio."
  },
  "servers": [
    {
      "url": "https://qurator.qapitol.ai",
      "description": "Production"
    },
    {
      "url": "http://api.localhost",
      "description": "Local freemium stack (Caddy)"
    },
    {
      "url": "http://localhost:8000",
      "description": "Local gateway direct"
    }
  ],
  "tags": [
    { "name": "Evaluation", "description": "Run assurance evaluations" },
    { "name": "History", "description": "Past evaluation runs and batches" },
    { "name": "Feedback & Calibration", "description": "Human review signals and progressive τ* operating points" },
    { "name": "Rubrics", "description": "Built-in and tenant custom rubrics" },
    { "name": "Annotations", "description": "Uploaded example evaluations (zero-credit golden labels)" },
    { "name": "Knowledge Bases", "description": "Self-serve document knowledge bases" },
    { "name": "Insights", "description": "Causal failure clusters and KPI overview" },
    { "name": "Account", "description": "Credits and workspace context" },
    { "name": "MCP", "description": "Read-only Model Context Protocol endpoint" }
  ],
  "paths": {
    "/evaluate": {
      "post": {
        "tags": ["Evaluation"],
        "summary": "Run assurance evaluation (unified)",
        "operationId": "evaluate",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EvaluateRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvaluateResult" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/evaluate": {
      "post": {
        "tags": ["Evaluation"],
        "summary": "Run assurance evaluation (assure namespace)",
        "operationId": "assureEvaluate",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EvaluateRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvaluateResult" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/evaluate-status": {
      "get": {
        "tags": ["Evaluation"],
        "summary": "Evaluate maintenance / availability status",
        "description": "Public read of evaluate availability (no API key required).",
        "operationId": "assureEvaluateStatus",
        "security": [],
        "responses": {
          "200": {
            "description": "Maintenance status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/trace/preview": {
      "post": {
        "tags": ["Evaluation"],
        "summary": "Validate and preview a trace envelope",
        "operationId": "assureTracePreview",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TracePreviewRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized preview",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TracePreviewResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/history/evaluations": {
      "get": {
        "tags": ["History"],
        "summary": "List evaluation history",
        "operationId": "assureHistoryEvaluations",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter: conversation | trace | agent_trace",
            "schema": { "type": "string" }
          },
          {
            "name": "batch",
            "in": "query",
            "description": "Filter by jsonl_batch_id",
            "schema": { "type": "string" }
          },
          {
            "name": "in_batch",
            "in": "query",
            "description": "yes = only JSONL batch lines; no = only non-batch runs",
            "schema": { "type": "string", "enum": ["yes", "no"] }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Trace id or external_id substring",
            "schema": { "type": "string" }
          },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "enum": ["pass", "warning", "fail"] }
          },
          {
            "name": "quality",
            "in": "query",
            "schema": { "type": "string", "enum": ["high", "medium", "low", "uncertain"] }
          },
          {
            "name": "date_from",
            "in": "query",
            "description": "Inclusive start date (YYYY-MM-DD)",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "date_to",
            "in": "query",
            "description": "Inclusive end date (YYYY-MM-DD)",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Evaluation list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvaluationListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/history/batches": {
      "get": {
        "tags": ["History"],
        "summary": "List evaluation batches",
        "operationId": "assureHistoryBatches",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          {
            "name": "search",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "date_from",
            "in": "query",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "outcome",
            "in": "query",
            "schema": { "type": "string", "enum": ["any_failure", "all_ready", "partial"] }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": { "type": "string", "enum": ["conversation", "trace"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Batch list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvaluationBatchListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/history/evaluations/{evaluation_id}": {
      "get": {
        "tags": ["History"],
        "summary": "Get evaluation detail",
        "operationId": "assureHistoryEvaluationDetail",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "evaluation_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Evaluation detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvaluationDetailResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/feedback": {
      "post": {
        "tags": ["Feedback & Calibration"],
        "summary": "Submit human feedback (confirm / override)",
        "description": "Accessible via API key. When include_in_tau applies, may trigger progressive τ* update.",
        "operationId": "assureFeedback",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AssureFeedbackRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback recorded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssureFeedbackResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/calibration": {
      "get": {
        "tags": ["Feedback & Calibration"],
        "summary": "Get progressive τ* calibration status",
        "operationId": "getCalibration",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "assurance_tier",
            "in": "query",
            "schema": { "type": "string", "enum": ["flash", "pro", "lightning"] }
          },
          {
            "name": "rubric_id",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Calibration status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CalibrationStatusResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/calibration/status": {
      "get": {
        "tags": ["Feedback & Calibration"],
        "summary": "Get progressive τ* calibration status (alias)",
        "operationId": "getCalibrationStatus",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "assurance_tier",
            "in": "query",
            "schema": { "type": "string", "enum": ["flash", "pro", "lightning"] }
          },
          {
            "name": "rubric_id",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Calibration status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CalibrationStatusResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/calibration/recompute": {
      "post": {
        "tags": ["Feedback & Calibration"],
        "summary": "Recompute tenant operating point (τ*)",
        "operationId": "recomputeCalibration",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CalibrationRecomputeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated operating point",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/v1/assure/rubrics": {
      "get": {
        "tags": ["Rubrics"],
        "summary": "List built-in and custom rubrics",
        "operationId": "listRubrics",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Rubric catalog",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssureRubricsListResponse" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Rubrics"],
        "summary": "Create a custom rubric",
        "description": "Freemium cap: 3 active custom rubrics. Paid: unlimited.",
        "operationId": "createRubric",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateRubricRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created rubric",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssureRubricItem" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/rubrics/{rubric_id}": {
      "put": {
        "tags": ["Rubrics"],
        "summary": "Update a custom rubric",
        "operationId": "updateRubric",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "rubric_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateRubricRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated rubric",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssureRubricItem" }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Rubrics"],
        "summary": "Soft-delete a custom rubric",
        "description": "Platform built-in rubrics return 403.",
        "operationId": "deleteRubric",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "rubric_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": { "type": "boolean" },
                    "rubric_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/annotations/batch": {
      "post": {
        "tags": ["Annotations"],
        "summary": "Upload example evaluations (batch)",
        "description": "PII-redacted golden labels; 0 credits. Freemium cap 25 total; Paid unlimited (500/batch).",
        "operationId": "uploadAnnotationsBatch",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AnnotationsBatchRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnnotationsBatchResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/annotations": {
      "get": {
        "tags": ["Annotations"],
        "summary": "List uploaded example evaluations",
        "operationId": "listAnnotations",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "rubric_id",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Annotation list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnnotationsListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/annotations/{trace_id}": {
      "delete": {
        "tags": ["Annotations"],
        "summary": "Delete an uploaded example evaluation",
        "operationId": "deleteAnnotation",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "trace_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": { "type": "boolean" },
                    "trace_id": { "type": "string" },
                    "calibration_update": { "type": "object", "additionalProperties": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/knowledge-bases": {
      "get": {
        "tags": ["Knowledge Bases"],
        "summary": "List knowledge bases",
        "operationId": "listKnowledgeBases",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "KB list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/KnowledgeBasesListResponse" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Knowledge Bases"],
        "summary": "Create a knowledge base",
        "description": "Freemium cap: 1 KB. Paid: unlimited.",
        "operationId": "createKnowledgeBase",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateKnowledgeBaseRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created KB",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/KnowledgeBase" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/knowledge-bases/{kb_id}/documents": {
      "post": {
        "tags": ["Knowledge Bases"],
        "summary": "Upload a document to a knowledge base",
        "description": "Accepts JSON `{filename, content, mime_type}` or multipart `file`. Formats: .md/.txt/.pdf/.docx. PII redacted per chunk.",
        "operationId": "uploadKnowledgeBaseDocument",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "kb_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UploadKbDocumentJsonRequest" }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload / dedup result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UploadKbDocumentResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/knowledge-bases/{kb_id}/documents/{doc_id}": {
      "delete": {
        "tags": ["Knowledge Bases"],
        "summary": "Delete a KB document",
        "operationId": "deleteKnowledgeBaseDocument",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "kb_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "doc_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": { "type": "boolean" },
                    "document_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/knowledge-bases/{kb_id}": {
      "delete": {
        "tags": ["Knowledge Bases"],
        "summary": "Delete a knowledge base",
        "description": "Returns 409 if attached to an active rubric or non-empty unless `force=true`.",
        "operationId": "deleteKnowledgeBase",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "kb_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "force",
            "in": "query",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": { "type": "boolean" },
                    "kb_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/insights/overview": {
      "get": {
        "tags": ["Insights"],
        "summary": "Insights KPI overview",
        "operationId": "insightsOverview",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "window_days",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }
          },
          {
            "name": "group_by_tag",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Overview KPIs",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/v1/assure/insights/clusters": {
      "get": {
        "tags": ["Insights"],
        "summary": "Causal failure mode clusters",
        "description": "Freemium: top 3 clusters in full; clusters #4+ locked. Paid: all clusters.",
        "operationId": "insightsClusters",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "window_days",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }
          },
          {
            "name": "rubric_id",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Clusters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InsightsClustersResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/insights/clusters/{cluster_id}/promote-rubric": {
      "post": {
        "tags": ["Insights"],
        "summary": "Promote a failure cluster to a rubric",
        "description": "Paid plan only (403 on Freemium).",
        "operationId": "promoteClusterRubric",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "cluster_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PromoteClusterRubricRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created rubric",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rubric_id": { "type": "string" },
                    "name": { "type": "string" },
                    "criteria": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/assure/usage/credits": {
      "get": {
        "tags": ["Account"],
        "summary": "Get credit usage for the current month",
        "operationId": "usageCredits",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Credits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UsageCreditsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/workspace": {
      "get": {
        "tags": ["Account"],
        "summary": "Get workspace context for the API key",
        "operationId": "assureWorkspace",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Workspace",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkspaceResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/assure/mcp": {
      "post": {
        "tags": ["MCP"],
        "summary": "Read-only MCP JSON-RPC 2.0",
        "description": "Streamable HTTP JSON-RPC (`initialize`, `tools/list`, `tools/call`). Tools: list_rubrics, list_traces, get_calibration, get_insights, get_failure_clusters, list_tag_keys, list_tag_values.",
        "operationId": "assureMcp",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "id": {},
                  "method": { "type": "string" },
                  "params": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Studio API key (`Authorization: Bearer <key>`)."
      }
    },
    "schemas": {
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"] },
          "content": { "type": "string" },
          "name": { "type": "string" },
          "tool_call_id": { "type": "string" }
        }
      },
      "EvaluateSources": {
        "type": "object",
        "description": "Toggle retrieval sources at evaluate time.",
        "properties": {
          "documents": { "type": "boolean" },
          "annotations": { "type": "boolean" },
          "memory": { "type": "boolean" },
          "calibration_tau": { "type": "boolean" }
        },
        "additionalProperties": { "type": "boolean" }
      },
      "EvaluateRequest": {
        "type": "object",
        "description": "Union: conversation (`messages`) or agent_trace (`trace`). Provide criteria and/or rubric_id / rubric_ids.",
        "properties": {
          "evaluate_kind": {
            "type": "string",
            "enum": ["conversation", "agent_trace"],
            "description": "Optional when messages or trace is present (auto-inferred)."
          },
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" },
            "minItems": 1
          },
          "trace": {
            "type": "object",
            "additionalProperties": true,
            "description": "Agent trace envelope (agent_trace)."
          },
          "criteria": { "type": "array", "items": { "type": "string" } },
          "rubric_id": { "type": "string" },
          "rubric_ids": { "type": "array", "items": { "type": "string" } },
          "assurance_tier": {
            "type": "string",
            "enum": ["flash", "pro", "lightning"],
            "default": "flash"
          },
          "mode": {
            "type": "string",
            "description": "Optional alias for assurance_tier"
          },
          "external_id": { "type": "string" },
          "test_case_id": { "type": "string" },
          "metadata": { "type": "object", "additionalProperties": true },
          "evaluate_latest": { "type": "boolean" },
          "voice_telemetry": { "type": "object", "additionalProperties": true },
          "voice_metadata": { "type": "object", "additionalProperties": true },
          "voice_turns": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "artifacts": { "type": "object", "additionalProperties": true },
          "kb_id": { "type": "string" },
          "sources": { "$ref": "#/components/schemas/EvaluateSources" },
          "ground_truth": {
            "description": "Optional reference answer or expected structured state.",
            "oneOf": [
              { "type": "string" },
              { "type": "object", "additionalProperties": true }
            ]
          },
          "tags": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Flat str tags (max 10 keys); filter with ?tag=key:value"
          }
        }
      },
      "EvaluateResult": {
        "type": "object",
        "properties": {
          "score": { "type": "number" },
          "status": { "type": "string" },
          "trace_id": { "type": "string" },
          "confidence": { "type": "number" },
          "quality_label": { "type": "string" },
          "explanation": { "type": "string" },
          "sources_used": {
            "type": "object",
            "additionalProperties": { "type": "boolean" }
          },
          "kb_chunks_used": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "tags": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          },
          "pass_threshold_tau": { "type": "number" },
          "credits_charged": { "type": "number" }
        },
        "additionalProperties": true
      },
      "TracePreviewRequest": {
        "type": "object",
        "required": ["trace"],
        "properties": {
          "trace": { "type": "object", "additionalProperties": true }
        }
      },
      "TracePreviewResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" }
          },
          "errors": { "type": "array", "items": { "type": "string" } }
        }
      },
      "EvaluationListItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" },
          "score": { "type": "number" },
          "confidence": { "type": "number" },
          "criteria_count": { "type": "integer" },
          "rubric_id": { "type": "string", "nullable": true },
          "credits_charged": { "type": "number", "nullable": true },
          "created_at": { "type": "string" },
          "external_id": { "type": "string", "nullable": true },
          "jsonl_batch_id": { "type": "string", "nullable": true },
          "jsonl_line": { "type": "integer", "nullable": true },
          "jsonl_total": { "type": "integer", "nullable": true },
          "jsonl_kind": { "type": "string", "nullable": true },
          "model_used": { "type": "string", "nullable": true },
          "review_recommended": { "type": "boolean" },
          "score_explanation_divergence": { "type": "boolean" }
        }
      },
      "EvaluationListResponse": {
        "type": "object",
        "properties": {
          "evaluations": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EvaluationListItem" }
          },
          "count": { "type": "integer" },
          "offset": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      },
      "EvaluationBatchListItem": {
        "type": "object",
        "properties": {
          "batch_id": { "type": "string" },
          "kind": { "type": "string", "nullable": true },
          "line_count": { "type": "integer" },
          "jsonl_total": { "type": "integer", "nullable": true },
          "partial": { "type": "boolean" },
          "ready_count": { "type": "integer" },
          "fail_count": { "type": "integer" },
          "mean_score": { "type": "number", "nullable": true },
          "credits_sum": { "type": "number" },
          "created_at_min": { "type": "string" }
        }
      },
      "EvaluationBatchListResponse": {
        "type": "object",
        "properties": {
          "batches": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EvaluationBatchListItem" }
          },
          "count": { "type": "integer" },
          "offset": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      },
      "EvaluationDetailResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" },
          "score": { "type": "number" },
          "confidence": { "type": "number" },
          "quality_label": { "type": "string", "nullable": true },
          "explanation": { "type": "string" },
          "evidence_for": { "type": "array", "items": { "type": "string" } },
          "evidence_against": { "type": "array", "items": { "type": "string" } },
          "gaps": { "type": "array", "items": { "type": "string" } },
          "severity": { "type": "string", "nullable": true },
          "score_explanation_divergence": { "type": "boolean" },
          "review_recommended": { "type": "boolean" },
          "model_used": { "type": "string", "nullable": true },
          "credits_charged": { "type": "number", "nullable": true },
          "created_at": { "type": "string" },
          "raw_submitted_json": { "type": "object", "additionalProperties": true },
          "feedback_vote": { "type": "string", "nullable": true },
          "rubric_scores": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true },
            "nullable": true
          },
          "pass_threshold_tau": { "type": "number", "nullable": true }
        },
        "additionalProperties": true
      },
      "AssureFeedbackRequest": {
        "type": "object",
        "required": ["trace_id"],
        "properties": {
          "trace_id": { "type": "string" },
          "vote": {
            "type": "string",
            "enum": ["up", "down"],
            "default": "up",
            "description": "Legacy signal. Prefer action=confirm|override."
          },
          "action": {
            "type": "string",
            "enum": ["confirm", "override"]
          },
          "sme_verdict": {
            "type": "string",
            "enum": ["pass", "fail"]
          },
          "reason_tag": {
            "type": "string",
            "enum": ["missed_violation", "false_alarm", "rubric_wording"]
          },
          "category": { "type": "string", "maxLength": 64 },
          "comment": { "type": "string", "maxLength": 500 },
          "skip_pairwise": { "type": "boolean", "default": true }
        }
      },
      "AssureFeedbackResponse": {
        "type": "object",
        "properties": {
          "feedback_id": { "type": "string" },
          "trace_id": { "type": "string" },
          "golden_kind": { "type": "string", "enum": ["golden_signal"] },
          "signal_vote": { "type": "string", "enum": ["up", "down"] },
          "sme_verdict": { "type": "string", "enum": ["pass", "fail"], "nullable": true },
          "reason_tag": { "type": "string", "nullable": true },
          "include_in_tau": { "type": "boolean" },
          "calibration_update": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true
          }
        }
      },
      "CalibrationStatusResponse": {
        "type": "object",
        "properties": {
          "operating_points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "assurance_tier": { "type": "string" },
                "rubric_id": { "type": "string", "nullable": true },
                "calibration_stage": { "type": "string" },
                "tau_star": { "type": "number" },
                "default_tau": { "type": "number" },
                "raw_tau_candidate": { "type": "number", "nullable": true },
                "shrinkage_lambda": { "type": "number", "nullable": true },
                "n_pass": { "type": "integer" },
                "n_fail": { "type": "integer" },
                "sample_size": { "type": "integer" },
                "method": { "type": "string", "nullable": true },
                "source": { "type": "string", "nullable": true },
                "min_verdicts_for_eb": { "type": "integer" },
                "min_fail_for_crc": { "type": "integer" }
              },
              "additionalProperties": true
            }
          },
          "uploaded_examples_count": { "type": "integer" },
          "knowledge_bases_count": { "type": "integer" },
          "client_id": { "type": "string" },
          "tenant_id": { "type": "string", "nullable": true }
        }
      },
      "CalibrationRecomputeRequest": {
        "type": "object",
        "properties": {
          "assurance_tier": {
            "type": "string",
            "enum": ["flash", "pro", "lightning"],
            "default": "pro"
          },
          "rubric_id": { "type": "string", "nullable": true },
          "target_alpha": { "type": "number", "default": 0.05 }
        }
      },
      "AssureRubricItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "criteria": { "type": "array", "items": { "type": "string" } },
          "gating": { "type": "boolean" },
          "is_custom": { "type": "boolean" },
          "knowledge_base_id": { "type": "string", "nullable": true }
        }
      },
      "AssureRubricsListResponse": {
        "type": "object",
        "properties": {
          "rubrics": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/AssureRubricItem" }
          },
          "count": { "type": "integer" },
          "offset": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      },
      "CreateRubricRequest": {
        "type": "object",
        "required": ["name", "criteria"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "criteria": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 1
          },
          "category": { "type": "string", "default": "custom" },
          "gating": { "type": "boolean", "default": true },
          "knowledge_base_id": { "type": "string", "nullable": true }
        }
      },
      "UpdateRubricRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "criteria": { "type": "array", "items": { "type": "string" } },
          "gating": { "type": "boolean" },
          "knowledge_base_id": { "type": "string", "nullable": true }
        }
      },
      "AnnotationExample": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" }
          },
          "criteria": { "type": "array", "items": { "type": "string" } },
          "verdict": { "type": "string", "enum": ["pass", "fail"] },
          "sme_verdict": { "type": "string", "enum": ["pass", "fail"] },
          "rationale": { "type": "string" },
          "comment": { "type": "string" },
          "reason_tag": { "type": "string" },
          "score": { "type": "number" },
          "rubric_id": { "type": "string" },
          "rubric_ids": { "type": "array", "items": { "type": "string" } },
          "input_text": { "type": "string" },
          "output_text": { "type": "string" }
        }
      },
      "AnnotationsBatchRequest": {
        "type": "object",
        "required": ["examples"],
        "properties": {
          "examples": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/AnnotationExample" },
            "minItems": 1
          },
          "assurance_tier": {
            "type": "string",
            "enum": ["flash", "pro", "lightning"],
            "default": "pro"
          }
        }
      },
      "AnnotationsBatchResponse": {
        "type": "object",
        "properties": {
          "uploaded_count": { "type": "integer" },
          "pii_redactions_applied": { "type": "integer" },
          "trace_ids": { "type": "array", "items": { "type": "string" } },
          "calibration_update": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true
          }
        }
      },
      "AnnotationsListResponse": {
        "type": "object",
        "properties": {
          "annotations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "trace_id": { "type": "string" },
                "score": { "type": "number" },
                "criteria": { "type": "array", "items": { "type": "string" } },
                "created_at": { "type": "string", "nullable": true },
                "rubric_id": { "type": "string", "nullable": true }
              }
            }
          },
          "count": { "type": "integer" }
        }
      },
      "CreateKnowledgeBaseRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true }
        }
      },
      "KnowledgeBase": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "document_count": { "type": "integer" },
          "chunk_count": { "type": "integer" },
          "total_bytes": { "type": "integer" },
          "attached_rubric_ids": {
            "type": "array",
            "items": { "type": "string" }
          },
          "created_at": { "type": "string", "nullable": true }
        }
      },
      "KnowledgeBasesListResponse": {
        "type": "object",
        "properties": {
          "knowledge_bases": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/KnowledgeBase" }
          },
          "count": { "type": "integer" }
        }
      },
      "UploadKbDocumentJsonRequest": {
        "type": "object",
        "properties": {
          "filename": { "type": "string", "default": "document.md" },
          "content": { "type": "string" },
          "mime_type": { "type": "string", "nullable": true }
        }
      },
      "UploadKbDocumentResponse": {
        "type": "object",
        "properties": {
          "document_id": { "type": "string" },
          "status": { "type": "string", "enum": ["ready", "deduplicated"] },
          "chunk_count": { "type": "integer" },
          "pii_redactions_count": { "type": "integer" },
          "sha256_digest": { "type": "string" }
        }
      },
      "InsightsClustersResponse": {
        "type": "object",
        "properties": {
          "clusters": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "count": { "type": "integer" }
        }
      },
      "PromoteClusterRubricRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "rubric_id": { "type": "string" }
        }
      },
      "UsageCreditsResponse": {
        "type": "object",
        "properties": {
          "month": { "type": "string" },
          "allowance": { "type": "number" },
          "used": { "type": "number" },
          "remaining": { "type": "number" },
          "eval_count": { "type": "integer" },
          "reset_note": { "type": "string" }
        }
      },
      "WorkspaceResponse": {
        "type": "object",
        "properties": {
          "org_name": { "type": "string" },
          "tenant_id": { "type": "string" },
          "client_id": { "type": "string" },
          "project_id": { "type": "string" },
          "plan_code": { "type": "string" },
          "allowed_assurance_tiers": {
            "type": "array",
            "items": { "type": "string" }
          },
          "calibration_anchors_used": { "type": "integer" },
          "calibration_anchor_cap": { "type": "integer", "nullable": true },
          "calibration_writes_enabled": { "type": "boolean" }
        },
        "additionalProperties": true
      }
    }
  }
}