{
  "openapi": "3.1.0",
  "info": {
    "title": "BoostOps API",
    "description": "Mobile app analytics REST API for AI agents and programmatic clients. Returns data with explicit provenance — every metric is tagged as `third_party_reported` (from Firebase/GA4 and app stores), `platform_reported` (from ETL pipeline), `attribution_derived` (from SKAN/ASA/MMP), or `computed` (by BoostOps). All responses include a `_meta` envelope with data freshness and source information.",
    "version": "1.2.0",
    "contact": {
      "name": "BoostOps",
      "url": "https://boostops.io"
    }
  },
  "servers": [
    {
      "url": "https://api.boostops.io",
      "description": "Production"
    },
    {
      "url": "http://localhost:3001",
      "description": "Local development"
    }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "tags": [
    { "name": "Apps", "description": "App/project listing and metadata" },
    { "name": "Overview", "description": "3rd-party reported analytics (Firebase/GA4) — same data as the Studio Overview dashboard (third_party_reported)" },
    { "name": "Metrics", "description": "ETL-processed metrics with provenance (platform_reported + attribution)" },
    { "name": "Revenue", "description": "Revenue focused view (platform_reported)" },
    { "name": "Installs", "description": "Install metrics with organic/paid split" },
    { "name": "Reviews", "description": "Store ratings and review history (platform_reported)" },
    { "name": "Health", "description": "App health assessment (computed from platform data)" },
    { "name": "Attribution", "description": "Channel and campaign attribution (attribution_derived)" },
    { "name": "Anomalies", "description": "Anomaly detection (computed from platform data)" },
    { "name": "Studio", "description": "Studio metadata" },
    { "name": "Portfolio", "description": "Cross-game portfolio rollup" },
    { "name": "Dashboard", "description": "Full studio dashboard in one call" }
  ],
  "paths": {
    "/api/v1/apps": {
      "get": {
        "operationId": "listApps",
        "summary": "List all apps in the studio",
        "description": "Returns all active apps with store metadata. Use the returned `id` values as `appId` in other endpoints.",
        "tags": ["Apps"],
        "responses": {
          "200": {
            "description": "List of apps",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } },
                    "count": { "type": "integer" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/apps/{appId}/overview": {
      "get": {
        "operationId": "getAppOverview",
        "summary": "Get app overview from 3rd-party platforms (third_party_reported)",
        "description": "Returns DAU, new users, and revenue as reported by connected 3rd-party platforms (Firebase/GA4, App Store Connect). This is the same data shown in the Studio Overview dashboard — no SDK required. Use this for daily active users and engagement KPIs. Use /metrics for ETL-processed attribution data.",
        "tags": ["Overview"],
        "parameters": [
          { "$ref": "#/components/parameters/AppId" },
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "App overview from 3rd-party platforms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppOverview" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/metrics": {
      "get": {
        "operationId": "getAppMetrics",
        "summary": "Get comprehensive app metrics with provenance",
        "description": "Returns `platform_metrics` (store-reported installs, revenue, DAU) and `attribution` (organic/paid split from SKAN/ASA/MMP). Each section is labeled with `_provenance` so you know where the data comes from. Note: DAU from this endpoint reflects ETL-processed data. For Firebase/GA4 DAU, use /overview.",
        "tags": ["Metrics"],
        "parameters": [
          { "$ref": "#/components/parameters/AppId" },
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Metrics with provenance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppMetrics" },
                    "_meta": { "$ref": "#/components/schemas/MetaFull" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/revenue": {
      "get": {
        "operationId": "getAppRevenue",
        "summary": "Get app revenue (platform_reported)",
        "description": "Revenue as reported by app stores (IAP + subscriptions). Does not include ad revenue unless fed into the ETL pipeline. Includes ARPU calculation.",
        "tags": ["Revenue"],
        "parameters": [
          { "$ref": "#/components/parameters/AppId" },
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Revenue data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppRevenue" },
                    "_meta": { "$ref": "#/components/schemas/MetaFull" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/installs": {
      "get": {
        "operationId": "getAppInstalls",
        "summary": "Get app install metrics with organic/paid breakdown",
        "description": "Returns `platform_reported` total installs and `attribution_derived` organic vs paid split. The organic/paid numbers may not sum to total due to unattributed installs.",
        "tags": ["Installs"],
        "parameters": [
          { "$ref": "#/components/parameters/AppId" },
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Install data with provenance split",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppInstalls" },
                    "_meta": { "$ref": "#/components/schemas/MetaFull" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/reviews": {
      "get": {
        "operationId": "getAppReviews",
        "summary": "Get store ratings and review history (platform_reported)",
        "description": "Ratings and review counts pulled from each app store. Includes 14-day rating trend history and per-platform breakdown.",
        "tags": ["Reviews"],
        "parameters": [{ "$ref": "#/components/parameters/AppId" }],
        "responses": {
          "200": {
            "description": "Review and rating data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppReviews" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/health": {
      "get": {
        "operationId": "getAppHealth",
        "summary": "Get app health assessment (computed)",
        "description": "Health status computed from store vitals, rating stability, ownership verification, and Firebase connectivity. Returns `overall_status` and specific `issues` with severity levels.",
        "tags": ["Health"],
        "parameters": [{ "$ref": "#/components/parameters/AppId" }],
        "responses": {
          "200": {
            "description": "Health assessment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppHealth" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/attribution": {
      "get": {
        "operationId": "getAppAttribution",
        "summary": "Get attribution data (attribution_derived)",
        "description": "Channel-level attribution from SKAN postbacks, Apple Search Ads events, and MMP integrations. Includes campaign CTR data. All data is attribution_derived — use /metrics for store-reported totals.",
        "tags": ["Attribution"],
        "parameters": [
          { "$ref": "#/components/parameters/AppId" },
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Attribution data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppAttribution" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/apps/{appId}/anomalies": {
      "get": {
        "operationId": "getAppAnomalies",
        "summary": "Get detected anomalies (computed)",
        "description": "Anomaly detection computed from platform-reported data: rating drops, DAU changes, revenue spikes/drops. Each anomaly includes its own `provenance` field indicating the underlying data source.",
        "tags": ["Anomalies"],
        "parameters": [{ "$ref": "#/components/parameters/AppId" }],
        "responses": {
          "200": {
            "description": "Anomaly results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppAnomalies" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/studio": {
      "get": {
        "operationId": "getStudio",
        "summary": "Get studio info",
        "description": "Basic information about the studio linked to the API key.",
        "tags": ["Studio"],
        "responses": {
          "200": {
            "description": "Studio info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Studio" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/portfolio/overview": {
      "get": {
        "operationId": "getPortfolioOverview",
        "summary": "Get studio-wide overview from 3rd-party platforms (third_party_reported)",
        "description": "Studio-wide DAU, new users, and revenue aggregated from connected 3rd-party platforms (Firebase/GA4). This is the same data shown in the Studio Overview dashboard. Shows per-app summaries and which apps have analytics connected vs disconnected.",
        "tags": ["Overview"],
        "parameters": [
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Portfolio overview from 3rd-party platforms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/PortfolioOverview" },
                    "_meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/portfolio/summary": {
      "get": {
        "operationId": "getPortfolioSummary",
        "summary": "Get cross-game portfolio rollup with provenance",
        "description": "Aggregated metrics across all apps in the studio from ETL data, with `platform_metrics` and `attribution_metrics` separated by provenance. Includes targets and campaign counts.",
        "tags": ["Portfolio"],
        "parameters": [
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Portfolio summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/PortfolioSummary" },
                    "_meta": { "$ref": "#/components/schemas/MetaFull" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/dashboard": {
      "get": {
        "operationId": "getDashboard",
        "summary": "Get everything in one call",
        "description": "Full studio dashboard: metrics (with provenance split), portfolio stats, per-app summaries, and target progress. Designed as the single endpoint an AI agent needs for a complete picture.",
        "tags": ["Dashboard"],
        "parameters": [
          { "$ref": "#/components/parameters/StartDate" },
          { "$ref": "#/components/parameters/EndDate" }
        ],
        "responses": {
          "200": {
            "description": "Dashboard overview",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Dashboard" },
                    "_meta": { "$ref": "#/components/schemas/MetaFull" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Studio API key. Format: bops_sk_{token}. Create keys in Settings > API Keys."
      }
    },
    "parameters": {
      "AppId": {
        "name": "appId",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "The app/project ID (use listApps to discover IDs)"
      },
      "StartDate": {
        "name": "start_date",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "format": "date" },
        "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago."
      },
      "EndDate": {
        "name": "end_date",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "format": "date" },
        "description": "End date (YYYY-MM-DD). Defaults to today."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } }
      },
      "Forbidden": {
        "description": "API key lacks required scope",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "description": "Lightweight metadata envelope",
        "properties": {
          "timestamp": { "type": "string", "format": "date-time" },
          "data_sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "type": { "type": "string", "enum": ["platform_reported", "attribution_derived", "computed"] }
              }
            }
          }
        }
      },
      "MetaFull": {
        "type": "object",
        "description": "Full metadata envelope with freshness and completeness info",
        "properties": {
          "timestamp": { "type": "string", "format": "date-time" },
          "analytics_connected": { "type": "boolean" },
          "days_with_data": { "type": "integer" },
          "freshness": {
            "type": "object",
            "nullable": true,
            "properties": {
              "most_recent_data": { "type": "string", "format": "date" },
              "lag_hours": { "type": "integer", "description": "Hours since most recent data point" }
            }
          },
          "data_sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "type": { "type": "string", "enum": ["platform_reported", "attribution_derived", "computed"] }
              }
            }
          }
        }
      },
      "Provenance": {
        "type": "string",
        "enum": ["third_party_reported", "platform_reported", "attribution_derived", "computed"],
        "description": "third_party_reported = from 3rd-party platform APIs (Firebase/GA4, stores). platform_reported = from ETL pipeline. attribution_derived = from SKAN/ASA/MMP. computed = calculated by BoostOps."
      },
      "AppOverview": {
        "type": "object",
        "description": "App overview from connected 3rd-party platforms. Same data as Studio Overview dashboard.",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "period": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } } },
          "_provenance": { "type": "string", "const": "third_party_reported" },
          "_description": { "type": "string" },
          "summary": {
            "type": "object",
            "nullable": true,
            "properties": {
              "avg_dau": { "type": "integer", "description": "Average daily active users from Firebase/GA4" },
              "peak_dau": { "type": "integer", "description": "Highest single-day DAU in period" },
              "total_new_users": { "type": "integer" },
              "total_revenue_usd": { "type": "number" },
              "days": { "type": "integer", "description": "Number of days with data" }
            }
          },
          "daily": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object",
              "properties": {
                "date": { "type": "string", "format": "date" },
                "dau": { "type": "integer" },
                "new_users": { "type": "integer" },
                "revenue_usd": { "type": "number" }
              }
            }
          }
        }
      },
      "PortfolioOverview": {
        "type": "object",
        "description": "Studio-wide overview aggregated from 3rd-party platforms. Shows per-app connectivity status.",
        "properties": {
          "studio": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } },
          "period": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } } },
          "_provenance": { "type": "string", "const": "third_party_reported" },
          "summary": {
            "type": "object",
            "nullable": true,
            "properties": {
              "avg_dau": { "type": "integer" },
              "peak_dau": { "type": "integer" },
              "total_new_users": { "type": "integer" },
              "total_revenue_usd": { "type": "number" },
              "days": { "type": "integer" }
            }
          },
          "apps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "app_id": { "type": "string" },
                "app_name": { "type": "string" },
                "platforms": { "type": "array", "items": { "type": "string" } },
                "analytics_connected": { "type": "boolean" },
                "summary": { "type": "object", "nullable": true }
              }
            }
          },
          "daily": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": { "type": "string", "format": "date" },
                "dau": { "type": "integer" },
                "new_users": { "type": "integer" },
                "revenue_usd": { "type": "number" }
              }
            }
          }
        }
      },
      "App": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "project_type": { "type": "string" },
          "platforms": { "type": "array", "items": { "type": "string" } },
          "store_apps": { "type": "array", "items": { "type": "object" } }
        }
      },
      "AppMetrics": {
        "type": "object",
        "description": "Comprehensive metrics with provenance. platform_metrics = store-reported, attribution = SKAN/ASA/MMP derived.",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "period": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } } },
          "platform_metrics": {
            "type": "object",
            "nullable": true,
            "properties": {
              "_provenance": { "type": "string", "const": "platform_reported" },
              "_description": { "type": "string" },
              "summary": {
                "type": "object",
                "properties": {
                  "total_installs": { "type": "integer" },
                  "revenue_usd": { "type": "number" },
                  "avg_dau": { "type": "integer", "nullable": true },
                  "paying_users": { "type": "integer" },
                  "impressions": { "type": "integer" }
                }
              },
              "daily": { "type": "array", "items": { "type": "object" } }
            }
          },
          "attribution": {
            "type": "object",
            "nullable": true,
            "properties": {
              "_provenance": { "type": "string", "const": "attribution_derived" },
              "_description": { "type": "string" },
              "summary": {
                "type": "object",
                "properties": {
                  "organic_installs": { "type": "integer" },
                  "paid_installs": { "type": "integer" },
                  "unattributed": { "type": "integer" },
                  "organic_pct": { "type": "number", "nullable": true }
                }
              },
              "daily": { "type": "array", "items": { "type": "object" } }
            }
          }
        }
      },
      "AppRevenue": {
        "type": "object",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "_provenance": { "type": "string", "const": "platform_reported" },
          "summary": {
            "type": "object",
            "nullable": true,
            "properties": {
              "total_revenue_usd": { "type": "number" },
              "avg_daily_revenue_usd": { "type": "number" },
              "total_paying_users": { "type": "integer" },
              "arpu": { "type": "number", "nullable": true, "description": "Average revenue per paying user" }
            }
          },
          "daily": { "type": "array", "nullable": true, "items": { "type": "object" } }
        }
      },
      "AppInstalls": {
        "type": "object",
        "description": "Installs split by provenance: platform_reported totals + attribution_derived organic/paid.",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "platform_reported": {
            "type": "object",
            "properties": {
              "_description": { "type": "string" },
              "total_installs": { "type": "integer" },
              "avg_daily_installs": { "type": "integer" }
            }
          },
          "attribution_derived": {
            "type": "object",
            "properties": {
              "_description": { "type": "string" },
              "organic_installs": { "type": "integer" },
              "paid_installs": { "type": "integer" },
              "unattributed": { "type": "integer" },
              "organic_pct": { "type": "number", "nullable": true }
            }
          }
        }
      },
      "AppReviews": {
        "type": "object",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "_provenance": { "type": "string", "const": "platform_reported" },
          "aggregate": {
            "type": "object",
            "properties": {
              "avg_rating": { "type": "number", "nullable": true },
              "total_reviews": { "type": "integer" },
              "platforms_tracked": { "type": "integer" }
            }
          },
          "platforms": { "type": "array", "items": { "type": "object" } }
        }
      },
      "AppHealth": {
        "type": "object",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "_provenance": { "type": "string", "const": "computed" },
          "overall_status": { "type": "string", "enum": ["healthy", "needs_attention", "critical"] },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "severity": { "type": "string", "enum": ["info", "warning", "critical"] },
                "area": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          },
          "stores": { "type": "array", "items": { "type": "object" } },
          "firebase": { "type": "object", "nullable": true }
        }
      },
      "AppAttribution": {
        "type": "object",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "_provenance": { "type": "string", "const": "attribution_derived" },
          "_description": { "type": "string" },
          "channels": { "type": "array", "nullable": true, "items": { "type": "object" } },
          "campaigns": { "type": "array", "nullable": true, "items": { "type": "object" } },
          "apple_search_ads": { "type": "object", "nullable": true }
        }
      },
      "AppAnomalies": {
        "type": "object",
        "properties": {
          "app_id": { "type": "string" },
          "app_name": { "type": "string" },
          "_provenance": { "type": "string", "const": "computed" },
          "anomaly_count": { "type": "integer" },
          "anomalies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "type": "string" },
                "severity": { "type": "string", "enum": ["info", "warning", "critical"] },
                "message": { "type": "string" },
                "provenance": { "type": "string", "description": "The provenance of the underlying signal" },
                "details": { "type": "object", "nullable": true }
              }
            }
          }
        }
      },
      "Studio": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "counts": {
            "type": "object",
            "properties": {
              "active_projects": { "type": "integer" },
              "active_members": { "type": "integer" },
              "active_campaigns": { "type": "integer" }
            }
          }
        }
      },
      "PortfolioSummary": {
        "type": "object",
        "description": "Portfolio rollup with platform_metrics and attribution_metrics separated by provenance.",
        "properties": {
          "studio": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } },
          "platform_metrics": {
            "type": "object",
            "nullable": true,
            "properties": {
              "_provenance": { "type": "string", "const": "platform_reported" },
              "total_installs": { "type": "integer" },
              "total_revenue_usd": { "type": "number" },
              "avg_dau": { "type": "integer", "nullable": true }
            }
          },
          "attribution_metrics": {
            "type": "object",
            "nullable": true,
            "properties": {
              "_provenance": { "type": "string", "const": "attribution_derived" },
              "organic_installs": { "type": "integer" },
              "paid_installs": { "type": "integer" },
              "organic_pct": { "type": "number", "nullable": true }
            }
          },
          "portfolio": { "type": "object" },
          "targets": { "type": "array", "items": { "type": "object" } }
        }
      },
      "Dashboard": {
        "type": "object",
        "description": "Complete studio dashboard. platform_metrics and attribution_metrics are separated by provenance.",
        "properties": {
          "studio": { "type": "object" },
          "platform_metrics": { "type": "object", "nullable": true },
          "attribution_metrics": { "type": "object", "nullable": true },
          "portfolio": { "type": "object" },
          "apps": { "type": "array", "items": { "type": "object" } },
          "targets": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}