{
  "openapi": "3.1.0",
  "info": {
    "title": "MO§ES™ API",
    "version": "0.1.0",
    "description": "Enterprise AI operator evaluation platform. MCP tools exposed as API endpoints for agent integration. All write operations require authorization.",
    "contact": {
      "name": "MO§ES™",
      "email": "burnmydays@proton.me",
      "url": "https://mos2es.org"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://mos2es.org/license"
    }
  },
  "servers": [
    {
      "url": "https://mos2es.org",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "read", "description": "Read-only queries (16 tools)" },
    { "name": "write", "description": "Write operations requiring authorization (5 tools)" }
  ],
  "paths": {
    "/api/pilot-status": {
      "get": {
        "operationId": "getPilotStatus",
        "tags": ["read"],
        "summary": "Get pilot status overview",
        "description": "Returns cohort size, observation count, date range, data quality summary, and active interventions.",
        "responses": {
          "200": {
            "description": "Pilot status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PilotStatus" }
              }
            }
          }
        }
      }
    },
    "/api/operator/{operatorId}": {
      "get": {
        "operationId": "getOperatorProfile",
        "tags": ["read"],
        "summary": "Get operator profile",
        "description": "Returns operator metrics, percentiles, benchmark availability, and divergence flags.",
        "parameters": [
          {
            "name": "operatorId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Pseudonymous operator ID (e.g., op_001)"
          }
        ],
        "responses": {
          "200": {
            "description": "Operator profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OperatorProfile" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/cohort/distribution": {
      "get": {
        "operationId": "getCohortDistribution",
        "tags": ["read"],
        "summary": "Get cohort metric distribution",
        "description": "Returns percentile bands (median, p25, p10, p5, p1) for a given metric across the cohort.",
        "parameters": [
          {
            "name": "metric",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "leverage" },
            "description": "Metric name: leverage, yield, token_snr, log_leverage, construction"
          }
        ],
        "responses": {
          "200": {
            "description": "Cohort distribution",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CohortDistribution" }
              }
            }
          }
        }
      }
    },
    "/api/composite-score/{operatorId}": {
      "get": {
        "operationId": "getCompositeScore",
        "tags": ["read"],
        "summary": "Get developmental composite score",
        "description": "Returns the 0-100 developmental composite score for an operator. Labeled DEVELOPMENTAL, not PERSONNEL. No punitive use.",
        "parameters": [
          {
            "name": "operatorId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Composite score",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompositeScore" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/composite-score/summary": {
      "get": {
        "operationId": "getCompositeScoreSummary",
        "tags": ["read"],
        "summary": "Get cohort composite score summary",
        "description": "Returns aggregate distribution of composite scores across the cohort. No individual rankings exposed.",
        "responses": {
          "200": {
            "description": "Score summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScoreSummary" }
              }
            }
          }
        }
      }
    },
    "/api/diagnostics/{operatorId}": {
      "get": {
        "operationId": "getDiagnostics",
        "tags": ["read"],
        "summary": "Get operator diagnostics",
        "description": "Returns pattern detections and diagnoses for an operator. All diagnoses are HYPOTHESIS, never fact.",
        "parameters": [
          {
            "name": "operatorId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagnostics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Diagnostics" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/data-quality": {
      "get": {
        "operationId": "getDataQuality",
        "tags": ["read"],
        "summary": "Get data quality report",
        "description": "Returns completeness, coverage, and validity metrics for the pilot dataset.",
        "responses": {
          "200": {
            "description": "Data quality report",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DataQuality" }
              }
            }
          }
        }
      }
    },
    "/api/dashboard": {
      "get": {
        "operationId": "getExecutiveDashboard",
        "tags": ["read"],
        "summary": "Get executive dashboard HTML",
        "description": "Returns a self-contained HTML dashboard with cohort overview, composite score distribution, top patterns, intervention outcomes, and workflow fit.",
        "responses": {
          "200": {
            "description": "Dashboard HTML",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/intervention": {
      "post": {
        "operationId": "assignIntervention",
        "tags": ["write"],
        "summary": "Assign intervention to operator",
        "description": "Assigns a targeted intervention to an operator. Requires authorization.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/InterventionAssignment" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Intervention assigned",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Intervention" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/intervention/{interventionId}/close": {
      "post": {
        "operationId": "closeIntervention",
        "tags": ["write"],
        "summary": "Close an intervention",
        "description": "Marks an intervention as closed with outcome notes. Requires authorization.",
        "parameters": [
          {
            "name": "interventionId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Intervention closed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Intervention" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/experiment": {
      "post": {
        "operationId": "createExperiment",
        "tags": ["write"],
        "summary": "Create an experiment",
        "description": "Creates a new experiment configuration. Requires authorization.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Experiment" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Experiment created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Experiment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/workflow-observation": {
      "post": {
        "operationId": "recordWorkflowObservation",
        "tags": ["write"],
        "summary": "Record a workflow fit observation",
        "description": "Records a workflow fit observation for an operator. Requires authorization.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WorkflowObservation" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Observation recorded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkflowObservation" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/outcome-dataset": {
      "post": {
        "operationId": "attachOutcomeDataset",
        "tags": ["write"],
        "summary": "Attach outcome dataset",
        "description": "Attaches an external outcome dataset for join analysis. Outcome joins are labeled ASSOCIATION, never CAUSATION. Requires authorization.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OutcomeDataset" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dataset attached",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OutcomeDataset" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Authorization required",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "description": "Error code" },
          "message": { "type": "string", "description": "Human-readable message" },
          "resolution": { "type": "string", "description": "Suggested resolution" }
        }
      },
      "PilotStatus": {
        "type": "object",
        "properties": {
          "cohort_size": { "type": "integer" },
          "observation_count": { "type": "integer" },
          "date_range": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } },
          "active_interventions": { "type": "integer" },
          "data_quality": { "type": "string" }
        }
      },
      "OperatorProfile": {
        "type": "object",
        "properties": {
          "operator_id": { "type": "string" },
          "metrics": { "type": "object" },
          "percentiles": { "type": "object" },
          "benchmarks_available": { "type": "array", "items": { "type": "string" } },
          "divergence_flags": { "type": "array", "items": { "type": "string" } }
        }
      },
      "CohortDistribution": {
        "type": "object",
        "properties": {
          "metric": { "type": "string" },
          "bands": { "type": "object", "properties": { "median": { "type": "number" }, "p25": { "type": "number" }, "p10": { "type": "number" }, "p5": { "type": "number" }, "p1": { "type": "number" }, "p01": { "type": "number" } } }
        }
      },
      "CompositeScore": {
        "type": "object",
        "properties": {
          "operator_id": { "type": "string" },
          "score": { "type": "number", "minimum": 0, "maximum": 100 },
          "label": { "type": "string", "description": "Always DEVELOPMENTAL" },
          "components": { "type": "object" },
          "caveats": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ScoreSummary": {
        "type": "object",
        "properties": {
          "cohort_size": { "type": "integer" },
          "distribution": { "type": "object" },
          "label": { "type": "string", "description": "Always DEVELOPMENTAL" },
          "individual_rankings": { "type": "boolean", "description": "Always false — no rankings exposed" }
        }
      },
      "Diagnostics": {
        "type": "object",
        "properties": {
          "operator_id": { "type": "string" },
          "patterns": { "type": "array", "items": { "type": "object" } },
          "diagnoses": { "type": "array", "items": { "type": "object" } },
          "status": { "type": "string", "description": "Always HYPOTHESIS" }
        }
      },
      "DataQuality": {
        "type": "object",
        "properties": {
          "completeness": { "type": "number" },
          "coverage": { "type": "number" },
          "validity": { "type": "number" },
          "issues": { "type": "array", "items": { "type": "string" } }
        }
      },
      "InterventionAssignment": {
        "type": "object",
        "required": ["operator_id", "intervention_type"],
        "properties": {
          "operator_id": { "type": "string" },
          "intervention_type": { "type": "string" },
          "notes": { "type": "string" }
        }
      },
      "Intervention": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "operator_id": { "type": "string" },
          "type": { "type": "string" },
          "status": { "type": "string" },
          "created_at": { "type": "string" }
        }
      },
      "Experiment": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "configuration": { "type": "object" }
        }
      },
      "WorkflowObservation": {
        "type": "object",
        "properties": {
          "operator_id": { "type": "string" },
          "workflow_id": { "type": "string" },
          "fit_score": { "type": "number" },
          "notes": { "type": "string" }
        }
      },
      "OutcomeDataset": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "source": { "type": "string" },
          "join_type": { "type": "string", "description": "Always ASSOCIATION" }
        }
      }
    }
  }
}