{
  "openapi": "3.1.0",
  "info": {
    "title": "Biascoin Fundamentals API",
    "version": "0.1.0",
    "description": "SEC-derived company fundamentals API plus the thin SaaS account, billing, and API key wrapper."
  },
  "servers": [
    {
      "url": "http://localhost:3001",
      "description": "Local development"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "CompanySummary": {
        "type": "object",
        "required": ["symbol", "cik", "name", "exchange", "sector", "industry"],
        "properties": {
          "symbol": { "type": "string" },
          "cik": { "type": "string" },
          "name": { "type": "string" },
          "exchange": { "type": ["string", "null"] },
          "sector": { "type": ["string", "null"] },
          "industry": { "type": ["string", "null"] }
        }
      },
      "AuthUser": {
        "type": "object",
        "required": ["id", "email", "name"],
        "properties": {
          "id": { "type": "integer" },
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" }
        }
      },
      "AuthRequestSignup": {
        "type": "object",
        "required": ["name", "email", "password"],
        "properties": {
          "name": { "type": "string", "minLength": 2 },
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "minLength": 8 }
        }
      },
      "AuthRequestLogin": {
        "type": "object",
        "required": ["email", "password"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "minLength": 8 }
        }
      },
      "AuthResponse": {
        "type": "object",
        "required": ["user", "token"],
        "properties": {
          "user": { "$ref": "#/components/schemas/AuthUser" },
          "token": { "type": "string" }
        }
      },
      "SubscriptionSnapshot": {
        "type": "object",
        "required": ["planId", "status", "requestsPerMinute", "requestsPerDay"],
        "properties": {
          "planId": { "type": "string", "enum": ["free", "pro_monthly"] },
          "status": { "type": "string" },
          "requestsPerMinute": { "type": "integer" },
          "requestsPerDay": { "type": "integer" }
        }
      },
      "BillingSnapshot": {
        "type": ["object", "null"],
        "properties": {
          "PlanId": { "type": "string" },
          "Status": { "type": "string" },
          "CurrentPeriodEnd": { "type": ["string", "null"], "format": "date-time" },
          "StripeCustomerId": { "type": ["string", "null"] },
          "StripeSubscriptionId": { "type": ["string", "null"] }
        }
      },
      "ApiKeyRecord": {
        "type": "object",
        "required": ["Id", "Label", "KeyPrefix", "IsActive", "CreatedAt", "LastUsedAt"],
        "properties": {
          "Id": { "type": "integer" },
          "Label": { "type": "string" },
          "KeyPrefix": { "type": "string" },
          "IsActive": { "type": "boolean" },
          "CreatedAt": { "type": ["string", "null"], "format": "date-time" },
          "LastUsedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "ApiKeyUsageSummary": {
        "type": "object",
        "required": ["requestsToday", "requestsLast30Days", "byKey"],
        "properties": {
          "requestsToday": { "type": "integer" },
          "requestsLast30Days": { "type": "integer" },
          "byKey": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "label", "keyPrefix", "isActive", "requestsToday", "requestsLast30Days"],
              "properties": {
                "id": { "type": "integer" },
                "label": { "type": "string" },
                "keyPrefix": { "type": "string" },
                "isActive": { "type": "boolean" },
                "requestsToday": { "type": "integer" },
                "requestsLast30Days": { "type": "integer" }
              }
            }
          }
        }
      },
      "AccountMeResponse": {
        "type": "object",
        "required": ["user", "subscription", "billing", "apiKeys", "usage"],
        "properties": {
          "user": { "$ref": "#/components/schemas/AuthUser" },
          "subscription": { "$ref": "#/components/schemas/SubscriptionSnapshot" },
          "billing": { "$ref": "#/components/schemas/BillingSnapshot" },
          "apiKeys": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ApiKeyRecord" }
          },
          "usage": { "$ref": "#/components/schemas/ApiKeyUsageSummary" }
        }
      },
      "CreateApiKeyRequest": {
        "type": "object",
        "required": ["label"],
        "properties": {
          "label": { "type": "string", "minLength": 2, "maxLength": 64 }
        }
      },
      "CreateApiKeyResponse": {
        "type": "object",
        "required": ["apiKey", "record"],
        "properties": {
          "apiKey": { "type": "string" },
          "record": {
            "type": "object",
            "required": ["Id", "Label", "KeyPrefix", "IsActive"],
            "properties": {
              "Id": { "type": "integer" },
              "Label": { "type": "string" },
              "KeyPrefix": { "type": "string" },
              "IsActive": { "type": "boolean" }
            }
          }
        }
      },
      "CheckoutSessionResponse": {
        "type": "object",
        "required": ["url", "id"],
        "properties": {
          "url": { "type": ["string", "null"], "format": "uri" },
          "id": { "type": "string" }
        }
      },
      "FilingSummary": {
        "type": "object",
        "required": ["accessionNo", "formType", "filingDate", "periodEnd", "sourceUrl"],
        "properties": {
          "accessionNo": { "type": "string" },
          "formType": { "type": "string" },
          "filingDate": { "type": "string", "format": "date" },
          "periodEnd": { "type": ["string", "null"], "format": "date" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "InsiderTradingFiling": {
        "type": "object",
        "required": [
          "accessionNo",
          "formType",
          "filingDate",
          "sourceUrl",
          "reportingOwnerName",
          "reportingOwnerCik",
          "reportingOwnerTitle",
          "isDirector",
          "isOfficer",
          "isTenPercentOwner",
          "isOther"
        ],
        "properties": {
          "accessionNo": { "type": "string" },
          "formType": { "type": "string" },
          "filingDate": { "type": "string", "format": "date" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "reportingOwnerName": { "type": ["string", "null"] },
          "reportingOwnerCik": { "type": ["string", "null"] },
          "reportingOwnerTitle": { "type": ["string", "null"] },
          "isDirector": { "type": "boolean" },
          "isOfficer": { "type": "boolean" },
          "isTenPercentOwner": { "type": "boolean" },
          "isOther": { "type": "boolean" }
        }
      },
      "InsiderTransaction": {
        "type": "object",
        "required": [
          "symbol",
          "accessionNo",
          "formType",
          "filingDate",
          "reportingOwnerName",
          "reportingOwnerTitle",
          "securityTitle",
          "transactionDate",
          "transactionCode",
          "transactionType",
          "acquiredDisposed",
          "shares",
          "pricePerShare",
          "sharesOwnedFollowing",
          "ownershipForm",
          "ownershipNature",
          "isDerivative",
          "sourceUrl"
        ],
        "properties": {
          "symbol": { "type": "string" },
          "accessionNo": { "type": "string" },
          "formType": { "type": "string" },
          "filingDate": { "type": "string", "format": "date" },
          "reportingOwnerName": { "type": ["string", "null"] },
          "reportingOwnerTitle": { "type": ["string", "null"] },
          "securityTitle": { "type": ["string", "null"] },
          "transactionDate": { "type": ["string", "null"], "format": "date" },
          "transactionCode": { "type": ["string", "null"] },
          "transactionType": { "type": "string", "enum": ["buy", "sell", "award", "exercise", "other"] },
          "acquiredDisposed": { "type": ["string", "null"], "enum": ["A", "D", null] },
          "shares": { "type": ["number", "null"] },
          "pricePerShare": { "type": ["number", "null"] },
          "sharesOwnedFollowing": { "type": ["number", "null"] },
          "ownershipForm": { "type": ["string", "null"], "enum": ["D", "I", null] },
          "ownershipNature": { "type": ["string", "null"] },
          "isDerivative": { "type": "boolean" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "InstitutionalManagerSummary": {
        "type": "object",
        "required": ["cik", "managerName", "filingCount", "latestReportPeriod"],
        "properties": {
          "cik": { "type": "string" },
          "managerName": { "type": "string" },
          "filingCount": { "type": "integer" },
          "latestReportPeriod": { "type": ["string", "null"], "format": "date" }
        }
      },
      "InstitutionalHolding": {
        "type": "object",
        "required": [
          "managerCik",
          "managerName",
          "accessionNo",
          "filingDate",
          "reportPeriod",
          "issuerName",
          "issuerSymbol",
          "titleOfClass",
          "cusip",
          "valueThousands",
          "shares",
          "sharesType",
          "putCall",
          "investmentDiscretion",
          "votingAuthoritySole",
          "votingAuthorityShared",
          "votingAuthorityNone"
        ],
        "properties": {
          "managerCik": { "type": "string" },
          "managerName": { "type": "string" },
          "accessionNo": { "type": "string" },
          "filingDate": { "type": "string", "format": "date" },
          "reportPeriod": { "type": ["string", "null"], "format": "date" },
          "issuerName": { "type": "string" },
          "issuerSymbol": { "type": ["string", "null"] },
          "titleOfClass": { "type": ["string", "null"] },
          "cusip": { "type": ["string", "null"] },
          "valueThousands": { "type": ["number", "null"] },
          "shares": { "type": ["number", "null"] },
          "sharesType": { "type": ["string", "null"] },
          "putCall": { "type": ["string", "null"] },
          "investmentDiscretion": { "type": ["string", "null"] },
          "votingAuthoritySole": { "type": ["number", "null"] },
          "votingAuthorityShared": { "type": ["number", "null"] },
          "votingAuthorityNone": { "type": ["number", "null"] }
        }
      },
      "InsiderFilingsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/InsiderTradingFiling" }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": { "type": "integer" },
              "notes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "InsiderTransactionsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/InsiderTransaction" }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": { "type": "integer" },
              "notes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "InstitutionalHoldingsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/InstitutionalHolding" }
          },
          "meta": {
            "type": "object",
            "properties": {
              "manager": { "$ref": "#/components/schemas/InstitutionalManagerSummary" },
              "count": { "type": "integer" },
              "notes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "BulkInstitutionalHoldingsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["manager", "holdings"],
              "properties": {
                "manager": { "$ref": "#/components/schemas/InstitutionalManagerSummary" },
                "holdings": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/InstitutionalHolding" }
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": { "type": "integer" },
              "requested_manager_ciks": {
                "type": "array",
                "items": { "type": "string" }
              },
              "notes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "NormalizedFundamentals": {
        "type": "object",
        "required": [
          "symbol",
          "periodType",
          "fiscalYear",
          "fiscalPeriod",
          "periodEnd",
          "revenue",
          "gross_profit",
          "operating_income",
          "net_income",
          "eps_basic",
          "eps_diluted",
          "cash_and_equivalents",
          "total_assets",
          "total_liabilities",
          "shareholders_equity",
          "operating_cash_flow",
          "capex",
          "free_cash_flow",
          "shares_outstanding_basic",
          "shares_outstanding_diluted"
        ],
        "properties": {
          "symbol": { "type": "string" },
          "periodType": { "type": "string", "enum": ["annual", "quarterly", "ttm"] },
          "fiscalYear": { "type": "integer" },
          "fiscalPeriod": { "type": "string" },
          "periodEnd": { "type": "string", "format": "date" },
          "revenue": { "type": ["number", "null"] },
          "gross_profit": { "type": ["number", "null"] },
          "operating_income": { "type": ["number", "null"] },
          "net_income": { "type": ["number", "null"] },
          "eps_basic": { "type": ["number", "null"] },
          "eps_diluted": { "type": ["number", "null"] },
          "cash_and_equivalents": { "type": ["number", "null"] },
          "total_assets": { "type": ["number", "null"] },
          "total_liabilities": { "type": ["number", "null"] },
          "shareholders_equity": { "type": ["number", "null"] },
          "operating_cash_flow": { "type": ["number", "null"] },
          "capex": { "type": ["number", "null"] },
          "free_cash_flow": { "type": ["number", "null"] },
          "shares_outstanding_basic": { "type": ["number", "null"] },
          "shares_outstanding_diluted": { "type": ["number", "null"] }
        }
      },
      "DerivedMetrics": {
        "type": "object",
        "required": [
          "symbol",
          "periodEnd",
          "gross_margin",
          "operating_margin",
          "net_margin",
          "current_ratio",
          "debt_to_equity",
          "roa",
          "roe",
          "fcf_margin",
          "ttm_revenue",
          "ttm_net_income",
          "revenue_yoy",
          "eps_yoy",
          "ocf_yoy"
        ],
        "properties": {
          "symbol": { "type": "string" },
          "periodEnd": { "type": "string", "format": "date" },
          "gross_margin": { "type": ["number", "null"] },
          "operating_margin": { "type": ["number", "null"] },
          "net_margin": { "type": ["number", "null"] },
          "current_ratio": { "type": ["number", "null"] },
          "debt_to_equity": { "type": ["number", "null"] },
          "roa": { "type": ["number", "null"] },
          "roe": { "type": ["number", "null"] },
          "fcf_margin": { "type": ["number", "null"] },
          "ttm_revenue": { "type": ["number", "null"] },
          "ttm_net_income": { "type": ["number", "null"] },
          "revenue_yoy": { "type": ["number", "null"] },
          "eps_yoy": { "type": ["number", "null"] },
          "ocf_yoy": { "type": ["number", "null"] }
        }
      },
      "DataQualityMeta": {
        "type": "object",
        "required": [
          "coverage_class",
          "completeness",
          "populated_fields",
          "total_fields",
          "missing_fields",
          "notes"
        ],
        "properties": {
          "coverage_class": {
            "type": "string",
            "enum": ["complete", "partial", "sector_limited"]
          },
          "completeness": { "type": "string" },
          "populated_fields": { "type": "integer" },
          "total_fields": { "type": "integer" },
          "missing_fields": {
            "type": "array",
            "items": { "type": "string" }
          },
          "notes": {
            "type": "array",
            "items": { "type": "string" }
          },
          "selected_period_end": { "type": ["string", "null"], "format": "date" },
          "selected_period_type": { "type": ["string", "null"], "enum": ["annual", "quarterly", "ttm", null] }
        }
      },
      "FundamentalsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "$ref": "#/components/schemas/NormalizedFundamentals" },
          "meta": { "$ref": "#/components/schemas/DataQualityMeta" }
        }
      },
      "MetricsResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "$ref": "#/components/schemas/DerivedMetrics" },
          "meta": { "$ref": "#/components/schemas/DataQualityMeta" }
        }
      },
      "FundamentalsListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/NormalizedFundamentals" }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": { "type": "integer" },
              "requested_symbols": {
                "type": "array",
                "items": { "type": "string" }
              },
              "notes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "FilingsResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FilingSummary" }
          }
        }
      },
      "ApiKeysListResponse": {
        "type": "object",
        "required": ["apiKeys"],
        "properties": {
          "apiKeys": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ApiKeyRecord" }
          }
        }
      },
      "WebhookAckResponse": {
        "type": "object",
        "required": ["received"],
        "properties": {
          "received": { "type": "boolean" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {}
            }
          }
        }
      }
    }
  },
  "paths": {
    "/auth/signup": {
      "post": {
        "summary": "Create a website account",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AuthRequestSignup" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "JWT bearer token and user summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthResponse" }
              }
            }
          },
          "409": {
            "description": "Email already in use",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "summary": "Log into the website account",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AuthRequestLogin" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT bearer token and user summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/account/me": {
      "get": {
        "summary": "Get account, billing, API key, and usage snapshot",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Account snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AccountMeResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/account/usage": {
      "get": {
        "summary": "Get API usage summary",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Usage summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKeyUsageSummary" }
              }
            }
          }
        }
      }
    },
    "/account/api-keys": {
      "get": {
        "summary": "List API keys",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "List API keys",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKeysListResponse" }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new API key",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created API key and record",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" }
              }
            }
          }
        }
      }
    },
    "/account/api-keys/{id}": {
      "delete": {
        "summary": "Revoke an API key",
        "security": [{ "BearerAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "204": {
            "description": "API key revoked"
          }
        }
      }
    },
    "/billing/checkout-session": {
      "post": {
        "summary": "Create a Stripe checkout session for the $10 monthly plan",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "201": {
            "description": "Stripe checkout session",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" }
              }
            }
          }
        }
      }
    },
    "/billing/webhook": {
      "post": {
        "summary": "Stripe webhook endpoint",
        "security": [],
        "parameters": [
          {
            "name": "stripe-signature",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook accepted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WebhookAckResponse" }
              }
            }
          },
          "400": {
            "description": "Missing signature",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}": {
      "get": {
        "summary": "Get company metadata",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Company metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanySummary" }
              }
            }
          },
          "401": {
            "description": "API key missing or invalid",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Symbol not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/filings": {
      "get": {
        "summary": "Get recent SEC filing metadata",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent filing metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FilingsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/fundamentals/latest": {
      "get": {
        "summary": "Get best available recent fundamentals row",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Best available recent fundamentals",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FundamentalsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/fundamentals/annual": {
      "get": {
        "summary": "Get recent annual fundamentals",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Annual fundamentals",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FundamentalsListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/fundamentals/quarterly": {
      "get": {
        "summary": "Get recent quarterly fundamentals",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 12 }
          }
        ],
        "responses": {
          "200": {
            "description": "Quarterly fundamentals",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FundamentalsListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/metrics/latest": {
      "get": {
        "summary": "Get latest derived metrics",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Derived metrics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MetricsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/insiders/latest": {
      "get": {
        "summary": "Get recent insider filing headers for a company",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent insider filing headers",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InsiderFilingsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/company/{symbol}/insiders/transactions": {
      "get": {
        "summary": "Get normalized insider transactions for a company",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized insider transactions",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InsiderTransactionsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/institutions/{managerCik}/holdings/latest": {
      "get": {
        "summary": "Get the latest quarterly 13F holdings for one manager CIK",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "managerCik",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Latest 13F holdings snapshot for one manager",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InstitutionalHoldingsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/institutions/holdings/latest": {
      "get": {
        "summary": "Get latest quarterly 13F holdings in bulk for multiple manager CIKs",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "managerCiks",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Comma-separated manager CIK list, up to 25 managers."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk 13F holdings snapshots grouped by manager",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BulkInstitutionalHoldingsResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/bulk/fundamentals": {
      "get": {
        "summary": "Get compact recent fundamentals for multiple symbols",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbols",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Comma-separated symbol list, up to 25 symbols."
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk fundamentals",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FundamentalsListResponse" }
              }
            }
          }
        }
      }
    }
  }
}