{
  "components": {
    "parameters": {
      "CompanyQuery": {
        "description": "Ticker, CIK, or company-name search term",
        "example": "apple",
        "in": "query",
        "name": "q",
        "required": true,
        "schema": {
          "minLength": 2,
          "type": "string"
        }
      },
      "EventType": {
        "description": "Optional normalized event type filter",
        "example": "current_report",
        "in": "query",
        "name": "eventType",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Form": {
        "description": "Optional SEC form filter",
        "example": "8-K",
        "in": "query",
        "name": "form",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "description": "Maximum records to return",
        "in": "query",
        "name": "limit",
        "required": false,
        "schema": {
          "default": 50,
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        }
      },
      "Since": {
        "description": "Inclusive filing date lower bound. ISO 8601 timestamps are accepted and normalized to their date.",
        "in": "query",
        "name": "since",
        "required": true,
        "schema": {
          "example": "2026-07-01",
          "format": "date",
          "type": "string"
        }
      },
      "Ticker": {
        "description": "Ticker symbol or 10-digit CIK",
        "example": "AAPL",
        "in": "path",
        "name": "ticker",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "Tickers": {
        "description": "Comma-separated ticker symbols or 10-digit CIKs. Maximum 25 entries per request.",
        "example": "AAPL,MSFT,NVDA",
        "in": "query",
        "name": "tickers",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Invalid request parameters"
      },
      "NotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Resource not found"
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Invalid or missing API key"
      }
    },
    "schemas": {
      "Change": {
        "properties": {
          "changeType": {
            "enum": [
              "new",
              "amended",
              "material_event"
            ],
            "example": "material_event",
            "type": "string"
          },
          "filing": {
            "$ref": "#/components/schemas/Filing"
          },
          "observedAt": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "changeType",
          "observedAt",
          "filing"
        ],
        "type": "object"
      },
      "ChangeListResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Change"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ChangeMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "ChangeMeta": {
        "properties": {
          "count": {
            "type": "integer"
          },
          "filters": {
            "properties": {
              "eventType": {
                "nullable": true,
                "type": "string"
              },
              "form": {
                "nullable": true,
                "type": "string"
              },
              "ticker": {
                "nullable": true,
                "type": "string"
              }
            },
            "type": "object"
          },
          "nextSince": {
            "format": "date",
            "nullable": true,
            "type": "string"
          },
          "notInvestmentAdvice": {
            "type": "boolean"
          },
          "since": {
            "format": "date",
            "type": "string"
          }
        },
        "required": [
          "count",
          "since",
          "nextSince",
          "filters",
          "notInvestmentAdvice"
        ],
        "type": "object"
      },
      "Company": {
        "properties": {
          "cik": {
            "example": "0000320193",
            "type": "string"
          },
          "exchange": {
            "example": "Nasdaq",
            "nullable": true,
            "type": "string"
          },
          "filingCount": {
            "example": 124,
            "type": "integer"
          },
          "latestFilingAt": {
            "format": "date",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "example": "Apple Inc.",
            "type": "string"
          },
          "ticker": {
            "example": "AAPL",
            "nullable": true,
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "cik",
          "ticker",
          "name",
          "exchange",
          "updatedAt",
          "filingCount",
          "latestFilingAt"
        ],
        "type": "object"
      },
      "CompanyProfile": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Company"
          },
          {
            "properties": {
              "forms": {
                "items": {
                  "$ref": "#/components/schemas/CountByForm"
                },
                "type": "array"
              },
              "latestFiling": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Filing"
                  }
                ],
                "nullable": true
              },
              "latestIngestedAt": {
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "latestIngestedAt",
              "forms",
              "latestFiling"
            ],
            "type": "object"
          }
        ]
      },
      "CompanyProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/CompanyProfile"
          },
          "meta": {
            "$ref": "#/components/schemas/StatsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "CompanySearchResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Company"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/SearchMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "CountByEventType": {
        "properties": {
          "count": {
            "example": 42,
            "type": "integer"
          },
          "eventType": {
            "example": "current_report",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CountByForm": {
        "properties": {
          "count": {
            "example": 42,
            "type": "integer"
          },
          "form": {
            "example": "8-K",
            "type": "string"
          }
        },
        "type": "object"
      },
      "DemoResponse": {
        "properties": {
          "data": {
            "properties": {
              "latestFilings": {
                "items": {
                  "$ref": "#/components/schemas/Filing"
                },
                "type": "array"
              },
              "latestInsiderTrades": {
                "items": {
                  "$ref": "#/components/schemas/Filing"
                },
                "type": "array"
              },
              "sampleQueries": {
                "items": {
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "endpoint": {
                      "type": "string"
                    },
                    "requiresSubscription": {
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "stats": {
                "properties": {
                  "companyCount": {
                    "type": "integer"
                  },
                  "filingCount": {
                    "type": "integer"
                  },
                  "latestIngestRun": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/HealthIngestRun"
                      }
                    ],
                    "nullable": true
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "meta": {
            "properties": {
              "docsUrl": {
                "type": "string"
              },
              "generatedAt": {
                "type": "string"
              },
              "notInvestmentAdvice": {
                "type": "boolean"
              },
              "sampleOnly": {
                "type": "boolean"
              },
              "subscribeUrl": {
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "ErrorResponse": {
        "properties": {
          "error": {
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "Event": {
        "properties": {
          "accessionNo": {
            "type": "string"
          },
          "companyName": {
            "type": "string"
          },
          "detailUrl": {
            "nullable": true,
            "type": "string"
          },
          "eventType": {
            "example": "current_report",
            "type": "string"
          },
          "filedAt": {
            "nullable": true,
            "type": "string"
          },
          "form": {
            "example": "8-K",
            "type": "string"
          },
          "items": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "ticker": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "EventListResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Event"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "Filing": {
        "properties": {
          "acceptanceDateTime": {
            "example": "20260701172000",
            "nullable": true,
            "type": "string"
          },
          "accessionNo": {
            "example": "0000320193-26-000001",
            "type": "string"
          },
          "cik": {
            "example": "0000320193",
            "type": "string"
          },
          "companyName": {
            "example": "Apple Inc.",
            "type": "string"
          },
          "detailUrl": {
            "example": "https://www.sec.gov/Archives/example.htm",
            "nullable": true,
            "type": "string"
          },
          "eventType": {
            "example": "current_report",
            "type": "string"
          },
          "filedAt": {
            "example": "2026-07-01",
            "nullable": true,
            "type": "string"
          },
          "form": {
            "example": "8-K",
            "type": "string"
          },
          "ingestedAt": {
            "nullable": true,
            "type": "string"
          },
          "isInlineXbrl": {
            "example": true,
            "type": "boolean"
          },
          "isXbrl": {
            "example": true,
            "type": "boolean"
          },
          "items": {
            "example": [
              "2.02",
              "9.01"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "primaryDocDescription": {
            "example": "Current report",
            "nullable": true,
            "type": "string"
          },
          "primaryDocument": {
            "example": "aapl-20260701.htm",
            "nullable": true,
            "type": "string"
          },
          "reportDate": {
            "example": "2026-07-01",
            "nullable": true,
            "type": "string"
          },
          "size": {
            "example": 125000,
            "nullable": true,
            "type": "integer"
          },
          "ticker": {
            "example": "AAPL",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "FilingListResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Filing"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "FilingSummaryResponse": {
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Filing"
              },
              {
                "properties": {
                  "notInvestmentAdvice": {
                    "example": true,
                    "type": "boolean"
                  },
                  "summary": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            ]
          }
        },
        "type": "object"
      },
      "HealthIngestRun": {
        "properties": {
          "createdAt": {
            "type": "string"
          },
          "status": {
            "example": "ok",
            "type": "string"
          },
          "target": {
            "example": "watchlist",
            "type": "string"
          }
        },
        "required": [
          "target",
          "status",
          "createdAt"
        ],
        "type": "object"
      },
      "HealthResponse": {
        "properties": {
          "companyCount": {
            "example": 8000,
            "type": "integer"
          },
          "filingCount": {
            "example": 1200,
            "type": "integer"
          },
          "latestIngestRun": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HealthIngestRun"
              }
            ],
            "nullable": true
          },
          "notInvestmentAdvice": {
            "example": true,
            "type": "boolean"
          },
          "status": {
            "example": "ok",
            "type": "string"
          },
          "version": {
            "example": "0.1.1",
            "type": "string"
          }
        },
        "required": [
          "status",
          "version",
          "companyCount",
          "filingCount",
          "latestIngestRun",
          "notInvestmentAdvice"
        ],
        "type": "object"
      },
      "IngestRun": {
        "properties": {
          "createdAt": {
            "type": "string"
          },
          "message": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "example": "ok",
            "type": "string"
          },
          "target": {
            "example": "AAPL",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Meta": {
        "properties": {
          "count": {
            "type": "integer"
          }
        },
        "required": [
          "count"
        ],
        "type": "object"
      },
      "RootResponse": {
        "properties": {
          "changes": {
            "example": "/v1/sec/changes?since=2026-07-01",
            "type": "string"
          },
          "companySearch": {
            "example": "/v1/sec/companies/search?q=apple",
            "type": "string"
          },
          "demo": {
            "example": "/demo",
            "type": "string"
          },
          "docs": {
            "example": "/openapi.json",
            "type": "string"
          },
          "markets": {
            "example": "/markets",
            "type": "string"
          },
          "name": {
            "example": "SEC Event Intelligence API",
            "type": "string"
          },
          "notInvestmentAdvice": {
            "example": true,
            "type": "boolean"
          },
          "stats": {
            "example": "/v1/sec/stats",
            "type": "string"
          },
          "status": {
            "example": "/health",
            "type": "string"
          },
          "version": {
            "example": "0.1.1",
            "type": "string"
          },
          "watchlistChanges": {
            "example": "/v1/sec/watchlist/changes?tickers=AAPL,MSFT&since=2026-07-01",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchMeta": {
        "properties": {
          "count": {
            "type": "integer"
          },
          "notInvestmentAdvice": {
            "type": "boolean"
          },
          "query": {
            "type": "string"
          }
        },
        "required": [
          "count",
          "query",
          "notInvestmentAdvice"
        ],
        "type": "object"
      },
      "Stats": {
        "properties": {
          "companyCount": {
            "type": "integer"
          },
          "eventTypes": {
            "items": {
              "$ref": "#/components/schemas/CountByEventType"
            },
            "type": "array"
          },
          "filingCount": {
            "type": "integer"
          },
          "forms": {
            "items": {
              "$ref": "#/components/schemas/CountByForm"
            },
            "type": "array"
          },
          "latestFiling": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Filing"
              }
            ],
            "nullable": true
          },
          "latestIngestRun": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IngestRun"
              }
            ],
            "nullable": true
          }
        },
        "type": "object"
      },
      "StatsMeta": {
        "properties": {
          "generatedAt": {
            "type": "string"
          },
          "notInvestmentAdvice": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "StatsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Stats"
          },
          "meta": {
            "$ref": "#/components/schemas/StatsMeta"
          }
        },
        "type": "object"
      },
      "ValidationActionCount": {
        "properties": {
          "action": {
            "example": "request",
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "lastSeenAt": {
            "nullable": true,
            "type": "string"
          },
          "market": {
            "example": "procurement",
            "type": "string"
          }
        },
        "required": [
          "market",
          "action",
          "count",
          "lastSeenAt"
        ],
        "type": "object"
      },
      "ValidationDailyCount": {
        "properties": {
          "action": {
            "example": "view",
            "type": "string"
          },
          "count": {
            "example": 3,
            "type": "integer"
          },
          "date": {
            "format": "date",
            "type": "string"
          },
          "market": {
            "example": "procurement",
            "type": "string"
          }
        },
        "required": [
          "date",
          "market",
          "action",
          "count"
        ],
        "type": "object"
      },
      "ValidationEvent": {
        "properties": {
          "action": {
            "type": "string"
          },
          "createdAt": {
            "type": "string"
          },
          "market": {
            "type": "string"
          },
          "path": {
            "nullable": true,
            "type": "string"
          },
          "referrer": {
            "nullable": true,
            "type": "string"
          },
          "target": {
            "nullable": true,
            "type": "string"
          },
          "userAgent": {
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "market",
          "action",
          "target",
          "path",
          "referrer",
          "userAgent",
          "createdAt"
        ],
        "type": "object"
      },
      "ValidationFunnel": {
        "properties": {
          "demos": {
            "example": 5,
            "type": "integer"
          },
          "downloads": {
            "example": 3,
            "type": "integer"
          },
          "lastSeenAt": {
            "nullable": true,
            "type": "string"
          },
          "lastStrongIntentAt": {
            "nullable": true,
            "type": "string"
          },
          "market": {
            "example": "procurement",
            "type": "string"
          },
          "rapidapiClicks": {
            "example": 1,
            "type": "integer"
          },
          "requests": {
            "example": 2,
            "type": "integer"
          },
          "strongIntent": {
            "example": 11,
            "type": "integer"
          },
          "viewToStrongIntentRate": {
            "example": 0.4,
            "nullable": true,
            "type": "number"
          },
          "views": {
            "example": 20,
            "type": "integer"
          }
        },
        "required": [
          "market",
          "views",
          "requests",
          "demos",
          "downloads",
          "rapidapiClicks",
          "strongIntent",
          "viewToStrongIntentRate",
          "lastSeenAt",
          "lastStrongIntentAt"
        ],
        "type": "object"
      },
      "ValidationMarketCount": {
        "properties": {
          "count": {
            "type": "integer"
          },
          "lastSeenAt": {
            "nullable": true,
            "type": "string"
          },
          "market": {
            "example": "procurement",
            "type": "string"
          }
        },
        "required": [
          "market",
          "count",
          "lastSeenAt"
        ],
        "type": "object"
      },
      "ValidationStats": {
        "properties": {
          "byAction": {
            "items": {
              "$ref": "#/components/schemas/ValidationActionCount"
            },
            "type": "array"
          },
          "byMarket": {
            "items": {
              "$ref": "#/components/schemas/ValidationMarketCount"
            },
            "type": "array"
          },
          "byTarget": {
            "items": {
              "$ref": "#/components/schemas/ValidationTargetActionCount"
            },
            "type": "array"
          },
          "daily": {
            "items": {
              "$ref": "#/components/schemas/ValidationDailyCount"
            },
            "type": "array"
          },
          "days": {
            "example": 30,
            "type": "integer"
          },
          "funnels": {
            "items": {
              "$ref": "#/components/schemas/ValidationFunnel"
            },
            "type": "array"
          },
          "recent": {
            "items": {
              "$ref": "#/components/schemas/ValidationEvent"
            },
            "type": "array"
          },
          "targetFunnels": {
            "items": {
              "$ref": "#/components/schemas/ValidationTargetFunnel"
            },
            "type": "array"
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "total",
          "days",
          "byMarket",
          "byAction",
          "byTarget",
          "funnels",
          "targetFunnels",
          "daily",
          "recent"
        ],
        "type": "object"
      },
      "ValidationStatsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ValidationStats"
          },
          "meta": {
            "$ref": "#/components/schemas/StatsMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "ValidationTargetActionCount": {
        "properties": {
          "action": {
            "example": "request",
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "lastSeenAt": {
            "nullable": true,
            "type": "string"
          },
          "market": {
            "example": "procurement",
            "type": "string"
          },
          "target": {
            "example": "data-feed-procurement-opportunities-csv",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "market",
          "target",
          "action",
          "count",
          "lastSeenAt"
        ],
        "type": "object"
      },
      "ValidationTargetFunnel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ValidationFunnel"
          },
          {
            "properties": {
              "target": {
                "example": "data-feed-procurement-opportunities-csv",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "target"
            ],
            "type": "object"
          }
        ]
      },
      "WatchlistChangeBucket": {
        "properties": {
          "changes": {
            "items": {
              "$ref": "#/components/schemas/Change"
            },
            "type": "array"
          },
          "count": {
            "example": 2,
            "type": "integer"
          },
          "ticker": {
            "example": "AAPL",
            "type": "string"
          }
        },
        "required": [
          "ticker",
          "count",
          "changes"
        ],
        "type": "object"
      },
      "WatchlistChangeListResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WatchlistChangeBucket"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/WatchlistChangeMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "WatchlistChangeMeta": {
        "properties": {
          "count": {
            "description": "Total changes across all requested tickers.",
            "type": "integer"
          },
          "filters": {
            "properties": {
              "eventType": {
                "nullable": true,
                "type": "string"
              },
              "form": {
                "nullable": true,
                "type": "string"
              },
              "limit": {
                "type": "integer"
              },
              "tickers": {
                "example": [
                  "AAPL",
                  "MSFT"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "nextSince": {
            "format": "date",
            "nullable": true,
            "type": "string"
          },
          "notInvestmentAdvice": {
            "type": "boolean"
          },
          "since": {
            "format": "date",
            "type": "string"
          },
          "tickerCount": {
            "type": "integer"
          }
        },
        "required": [
          "count",
          "tickerCount",
          "since",
          "nextSince",
          "filters",
          "notInvestmentAdvice"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "AllThingsDevProxySecret": {
        "description": "Shared secret configured between AllThingsDev and the backend.",
        "in": "header",
        "name": "x-atd-proxy-secret",
        "type": "apiKey"
      },
      "ApiKeyAuth": {
        "description": "Direct backend API key for non-marketplace traffic.",
        "in": "header",
        "name": "x-api-key",
        "type": "apiKey"
      },
      "BearerAuth": {
        "description": "Alternative direct backend API key format.",
        "scheme": "bearer",
        "type": "http"
      },
      "RapidApiProxySecret": {
        "description": "Shared secret configured between RapidAPI and the backend.",
        "in": "header",
        "name": "x-rapidapi-proxy-secret",
        "type": "apiKey"
      }
    }
  },
  "externalDocs": {
    "description": "Documentation, examples, pricing, and direct access",
    "url": "https://api.data-apis.com/docs"
  },
  "info": {
    "contact": {
      "email": "api@data-apis.com",
      "name": "Data APIs",
      "url": "https://api.data-apis.com"
    },
    "description": "Normalized SEC EDGAR filing events for automation, screening, and market monitoring workflows. Use it for SEC filing change feeds, ticker watchlists, company lookup, insider filing metadata, and filing summaries. This API is data infrastructure only and does not provide investment advice.",
    "termsOfService": "https://api.data-apis.com/terms",
    "title": "SEC Event Intelligence API",
    "version": "0.1.1",
    "x-logo": {
      "altText": "Data APIs logo",
      "url": "https://api.data-apis.com/logo.svg"
    }
  },
  "openapi": "3.0.3",
  "paths": {
    "/": {
      "get": {
        "operationId": "getRoot",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RootResponse"
                }
              }
            },
            "description": "API metadata"
          }
        },
        "summary": "API metadata",
        "tags": [
          "System"
        ]
      }
    },
    "/demo": {
      "get": {
        "operationId": "getDemo",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoResponse"
                }
              }
            },
            "description": "Small unauthenticated sample for evaluation"
          }
        },
        "summary": "Public demo response",
        "tags": [
          "System"
        ]
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            },
            "description": "Service is alive"
          }
        },
        "summary": "Health check",
        "tags": [
          "System"
        ]
      }
    },
    "/v1/sec/changes": {
      "get": {
        "operationId": "getFilingChanges",
        "parameters": [
          {
            "$ref": "#/components/parameters/Since"
          },
          {
            "description": "Optional ticker or 10-digit CIK filter",
            "example": "AAPL",
            "in": "query",
            "name": "ticker",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Form"
          },
          {
            "$ref": "#/components/parameters/EventType"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangeListResponse"
                }
              }
            },
            "description": "Normalized filing changes"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Filing change feed since a date",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/companies/search": {
      "get": {
        "operationId": "searchCompanies",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyQuery"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanySearchResponse"
                }
              }
            },
            "description": "Matching SEC companies"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Search SEC companies by ticker, CIK, or name",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/company/{ticker}/events": {
      "get": {
        "operationId": "getCompanyEvents",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ticker"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventListResponse"
                }
              }
            },
            "description": "Normalized company events"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Company event feed by ticker or CIK",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/company/{ticker}/filings": {
      "get": {
        "operationId": "getCompanyFilings",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ticker"
          },
          {
            "$ref": "#/components/parameters/Form"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilingListResponse"
                }
              }
            },
            "description": "Filings for a company"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Company filings by ticker or CIK",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/company/{ticker}/profile": {
      "get": {
        "operationId": "getCompanyProfile",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ticker"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyProfileResponse"
                }
              }
            },
            "description": "Company metadata and filing coverage"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Company profile by ticker or CIK",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/forms/{accessionNo}/summary": {
      "get": {
        "operationId": "getFilingSummary",
        "parameters": [
          {
            "description": "SEC accession number",
            "example": "0000320193-26-000001",
            "in": "path",
            "name": "accessionNo",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilingSummaryResponse"
                }
              }
            },
            "description": "Filing summary"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Single filing summary",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/insider-trades": {
      "get": {
        "operationId": "getInsiderTrades",
        "parameters": [
          {
            "description": "Optional ticker or 10-digit CIK filter",
            "example": "AAPL",
            "in": "query",
            "name": "ticker",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilingListResponse"
                }
              }
            },
            "description": "Insider ownership filings"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Forms 3, 4, and 5",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/latest": {
      "get": {
        "operationId": "getLatestFilings",
        "parameters": [
          {
            "$ref": "#/components/parameters/Form"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilingListResponse"
                }
              }
            },
            "description": "Latest normalized filings"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Latest SEC filings",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/sec/stats": {
      "get": {
        "operationId": "getStats",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            },
            "description": "Service statistics"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Database and ingest statistics",
        "tags": [
          "System"
        ]
      }
    },
    "/v1/sec/watchlist/changes": {
      "get": {
        "operationId": "getWatchlistChanges",
        "parameters": [
          {
            "$ref": "#/components/parameters/Tickers"
          },
          {
            "$ref": "#/components/parameters/Since"
          },
          {
            "$ref": "#/components/parameters/Form"
          },
          {
            "$ref": "#/components/parameters/EventType"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WatchlistChangeListResponse"
                }
              }
            },
            "description": "Normalized filing changes grouped by ticker"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Filing change feed for a ticker watchlist",
        "tags": [
          "SEC Filings"
        ]
      }
    },
    "/v1/validation/stats": {
      "get": {
        "operationId": "getValidationStats",
        "parameters": [
          {
            "description": "Maximum recent events to return",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Daily breakdown lookback window",
            "in": "query",
            "name": "days",
            "required": false,
            "schema": {
              "default": 30,
              "maximum": 365,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationStatsResponse"
                }
              }
            },
            "description": "Validation click and request statistics"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Market-validation event statistics",
        "tags": [
          "Validation"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production backend",
      "url": "https://api.data-apis.com"
    },
    {
      "description": "Local development",
      "url": "http://127.0.0.1:8000"
    }
  ],
  "tags": [
    {
      "description": "Health, metadata, and service stats",
      "name": "System"
    },
    {
      "description": "Normalized SEC EDGAR filing data",
      "name": "SEC Filings"
    },
    {
      "description": "Market-validation intent tracking",
      "name": "Validation"
    }
  ]
}