{
 "components": {
  "parameters": {
   "limit": {
    "in": "query",
    "name": "limit",
    "schema": {
     "default": 100,
     "maximum": 1000,
     "type": "integer"
    }
   },
   "ticker": {
    "description": "Case-insensitive; class shares accept BRK.B or BRK-B",
    "example": "AAPL",
    "in": "path",
    "name": "ticker",
    "required": true,
    "schema": {
     "type": "string"
    }
   }
  },
  "responses": {
   "BadRequest": {
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    },
    "description": "Malformed request"
   },
   "NotFound": {
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    },
    "description": "Resource not found"
   },
   "RateLimited": {
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    },
    "description": "Rate limit or quota exceeded (see error.code)"
   },
   "Unauthorized": {
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    },
    "description": "Missing or invalid API key"
   }
  },
  "schemas": {
   "Company": {
    "properties": {
     "cik": {
      "example": 320193,
      "type": "integer"
     },
     "exchanges": {
      "example": "Nasdaq",
      "type": "string"
     },
     "name": {
      "example": "Apple Inc.",
      "type": "string"
     },
     "sic": {
      "example": "3571",
      "type": "string"
     },
     "sic_description": {
      "example": "Electronic Computers",
      "type": "string"
     },
     "ticker": {
      "example": "AAPL",
      "type": "string"
     },
     "updated_at": {
      "format": "date-time",
      "type": "string"
     }
    },
    "type": "object"
   },
   "EnrichedEvent": {
    "description": "One LLM-enriched structured event derived from an 8-K filing. Fields marked model-derived are extracted once at ingest by the enrichment stage and served deterministically — the model never runs per request.",
    "properties": {
     "accession_number": {
      "type": "string"
     },
     "company_name": {
      "type": "string"
     },
     "effective_date": {
      "description": "YYYY-MM-DD when stated, else absent",
      "type": "string"
     },
     "enriched_at": {
      "format": "date-time",
      "type": "string"
     },
     "event_type": {
      "description": "Model-derived, closed taxonomy",
      "enum": [
       "results_announcement",
       "guidance_update",
       "officer_departure",
       "officer_appointment",
       "officer_change",
       "director_change",
       "material_agreement",
       "agreement_termination",
       "debt_financing",
       "equity_issuance",
       "dividend_or_buyback",
       "restructuring",
       "impairment",
       "compensation_arrangement",
       "delisting_notice",
       "auditor_change",
       "going_concern",
       "control_change",
       "shareholder_meeting",
       "bylaws_amendment",
       "cybersecurity_incident",
       "regulation_fd",
       "legal_proceeding",
       "exhibits_only",
       "other"
      ],
      "type": "string"
     },
     "filing_date": {
      "format": "date",
      "type": "string"
     },
     "filing_url": {
      "type": "string"
     },
     "headline": {
      "description": "Model-derived, \u003c=100 chars",
      "type": "string"
     },
     "items": {
      "description": "8-K item codes reported in the filing",
      "items": {
       "type": "string"
      },
      "type": "array"
     },
     "materiality": {
      "description": "Model-derived investor-impact rating",
      "enum": [
       "high",
       "medium",
       "low"
      ],
      "type": "string"
     },
     "model_rev": {
      "description": "Enrichment prompt/taxonomy revision that produced this row",
      "type": "string"
     },
     "persons": {
      "description": "Model-derived named individuals central to the event",
      "items": {
       "properties": {
        "action": {
         "enum": [
          "appointed",
          "departed",
          "elected",
          "nominated",
          "retired",
          "other"
         ],
         "type": "string"
        },
        "name": {
         "type": "string"
        },
        "role": {
         "type": "string"
        }
       },
       "type": "object"
      },
      "type": "array"
     },
     "succession": {
      "type": "boolean"
     },
     "summary": {
      "description": "Model-derived, \u003c=60 words, facts only",
      "type": "string"
     },
     "ticker": {
      "type": "string"
     }
    },
    "type": "object"
   },
   "Error": {
    "properties": {
     "error": {
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      },
      "type": "object"
     }
    },
    "type": "object"
   },
   "Event8K": {
    "properties": {
     "accepted_at": {
      "type": "string"
     },
     "accession_number": {
      "type": "string"
     },
     "cik": {
      "type": "integer"
     },
     "company_name": {
      "type": "string"
     },
     "filing_date": {
      "format": "date",
      "type": "string"
     },
     "item": {
      "example": "2.02",
      "type": "string"
     },
     "ticker": {
      "example": "TSLA",
      "type": "string"
     }
    },
    "type": "object"
   },
   "Fact": {
    "properties": {
     "accession_number": {
      "type": "string"
     },
     "cik": {
      "type": "integer"
     },
     "end_date": {
      "format": "date",
      "type": "string"
     },
     "filed": {
      "format": "date",
      "type": "string"
     },
     "form": {
      "example": "10-Q",
      "type": "string"
     },
     "fp": {
      "example": "Q2",
      "type": "string"
     },
     "fy": {
      "example": 2026,
      "type": "integer"
     },
     "label": {
      "type": "string"
     },
     "start_date": {
      "format": "date",
      "type": "string"
     },
     "tag": {
      "example": "Revenues",
      "type": "string"
     },
     "taxonomy": {
      "example": "us-gaap",
      "type": "string"
     },
     "unit": {
      "example": "USD",
      "type": "string"
     },
     "value": {
      "example": 254940000000,
      "type": "number"
     }
    },
    "type": "object"
   },
   "Filing": {
    "properties": {
     "accepted_at": {
      "type": "string"
     },
     "accession_number": {
      "example": "0000320193-26-000013",
      "type": "string"
     },
     "cik": {
      "type": "integer"
     },
     "filing_date": {
      "format": "date",
      "type": "string"
     },
     "form": {
      "example": "10-Q",
      "type": "string"
     },
     "is_xbrl": {
      "type": "boolean"
     },
     "items": {
      "description": "8-K item codes, comma-separated",
      "type": "string"
     },
     "primary_document": {
      "type": "string"
     },
     "report_date": {
      "format": "date",
      "type": "string"
     },
     "size": {
      "type": "integer"
     }
    },
    "type": "object"
   },
   "InsiderTransaction": {
    "properties": {
     "accession_number": {
      "type": "string"
     },
     "acquired_disposed": {
      "enum": [
       "A",
       "D"
      ],
      "type": "string"
     },
     "cik": {
      "type": "integer"
     },
     "is_derivative": {
      "type": "boolean"
     },
     "is_director": {
      "type": "boolean"
     },
     "is_officer": {
      "type": "boolean"
     },
     "is_ten_percent_owner": {
      "type": "boolean"
     },
     "owner_cik": {
      "type": "integer"
     },
     "owner_name": {
      "example": "COOK TIMOTHY D",
      "type": "string"
     },
     "owner_title": {
      "example": "Chief Executive Officer",
      "type": "string"
     },
     "ownership_form": {
      "enum": [
       "D",
       "I"
      ],
      "type": "string"
     },
     "price_per_share": {
      "type": "number"
     },
     "security_title": {
      "example": "Common Stock",
      "type": "string"
     },
     "shares": {
      "type": "number"
     },
     "shares_owned_after": {
      "type": "number"
     },
     "transaction_code": {
      "example": "S",
      "type": "string"
     },
     "transaction_date": {
      "format": "date",
      "type": "string"
     }
    },
    "type": "object"
   },
   "WebhookPayload": {
    "description": "Body POSTed to your endpoint for each matching event",
    "properties": {
     "event": {
      "$ref": "#/components/schemas/Event8K"
     },
     "filing_url": {
      "example": "https://www.sec.gov/Archives/edgar/data/1318605/000162828026046717",
      "type": "string"
     },
     "sent_at": {
      "format": "date-time",
      "type": "string"
     },
     "type": {
      "example": "sec.8k.filed",
      "type": "string"
     }
    },
    "type": "object"
   },
   "WebhookSubscription": {
    "properties": {
     "active": {
      "type": "boolean"
     },
     "created_at": {
      "format": "date-time",
      "type": "string"
     },
     "id": {
      "type": "integer"
     },
     "items": {
      "type": "string"
     },
     "secret": {
      "description": "HMAC key — returned only at creation",
      "type": "string"
     },
     "tickers": {
      "type": "string"
     },
     "url": {
      "type": "string"
     }
    },
    "type": "object"
   }
  },
  "securitySchemes": {
   "apiKeyAuth": {
    "in": "header",
    "name": "X-API-Key",
    "type": "apiKey"
   },
   "bearerAuth": {
    "bearerFormat": "fj_...",
    "scheme": "bearer",
    "type": "http"
   }
  }
 },
 "info": {
  "contact": {
   "email": "danielrwilliamson27@gmail.com"
  },
  "description": "SEC filings, XBRL facts, and 8-K events as clean JSON + webhooks.\n\n**Data source:** [SEC EDGAR](https://www.sec.gov/edgar). FilingsJSON normalizes EDGAR's raw JSON/XML into stable, queryable resources and pushes new 8-K events to your webhooks within minutes of acceptance.\n\n## Quickstart (under 5 minutes)\n\n1. **Get a key** — `curl -X POST {host}/signup/free-key -d '{\"email\":\"you@example.com\"}'` (free tier: 100 calls/day) or reserve a founding key at the pricing page.\n2. **First call** — `curl -H 'Authorization: Bearer fj_...' {host}/v1/company/AAPL/facts?tag=Revenues`\n3. **Subscribe to events** — `POST /v1/webhooks/sec-events` with your endpoint URL; verify deliveries with the `X-FilingsJSON-Signature` HMAC header.\n\nAuthenticate with `Authorization: Bearer fj_...` or `X-API-Key: fj_...`. Rate limits and quotas per plan are returned in `X-Quota-*` headers.",
  "title": "FilingsJSON API",
  "version": "1.0.0"
 },
 "openapi": "3.1.0",
 "paths": {
  "/healthz": {
   "get": {
    "operationId": "healthz",
    "responses": {
     "200": {
      "description": "Service is up"
     }
    },
    "security": [],
    "summary": "Liveness probe"
   }
  },
  "/signup/free-key": {
   "post": {
    "description": "Self-serve free tier: 100 calls/day. One key per email.",
    "operationId": "signupFreeKey",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "email": {
          "format": "email",
          "type": "string"
         },
         "name": {
          "type": "string"
         }
        },
        "required": [
         "email"
        ],
        "type": "object"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "api_key": {
           "type": "string"
          },
          "plan": {
           "type": "string"
          },
          "quota": {
           "type": "integer"
          },
          "quota_period": {
           "type": "string"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Key issued (shown once)"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "409": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "Email already registered"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    },
    "security": [],
    "summary": "Get a free API key (no auth required)",
    "tags": [
     "Keys"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -X POST http://localhost:8080/signup/free-key \\\n  -d '{\"email\":\"you@example.com\"}'"
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.post(\n    \"http://localhost:8080/signup/free-key\",\n    json={\"email\": \"you@example.com\"},\n)\nFJ_KEY = r.json()[\"api_key\"]  # store it — shown once"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\"http://localhost:8080/signup/free-key\", {\n  method: \"POST\",\n  body: JSON.stringify({ email: \"you@example.com\" }),\n});\nconst { api_key } = await r.json(); // store it — shown once"
     }
    ]
   }
  },
  "/v1/companies": {
   "get": {
    "operationId": "listCompanies",
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "companies": {
           "items": {
            "$ref": "#/components/schemas/Company"
           },
           "type": "array"
          },
          "count": {
           "type": "integer"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Tracked universe"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    },
    "summary": "List tracked companies",
    "tags": [
     "Companies"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  http://localhost:8080/v1/companies"
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/companies\",\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nprint(r.json()[\"companies\"][0])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\"http://localhost:8080/v1/companies\", {\n  headers: { Authorization: `Bearer ${FJ_KEY}` },\n});\nconst { companies } = await r.json();\nconsole.log(companies[0]);"
     }
    ]
   }
  },
  "/v1/company/{ticker}/facts": {
   "get": {
    "description": "The most recent datapoint per (taxonomy, tag, unit). Filter to one concept with `tag`.",
    "operationId": "companyFacts",
    "parameters": [
     {
      "$ref": "#/components/parameters/ticker"
     },
     {
      "description": "XBRL concept, e.g. `Revenues`, `NetIncomeLoss`, `EarningsPerShareDiluted`",
      "in": "query",
      "name": "tag",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "company": {
           "$ref": "#/components/schemas/Company"
          },
          "count": {
           "type": "integer"
          },
          "facts": {
           "items": {
            "$ref": "#/components/schemas/Fact"
           },
           "type": "array"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Latest facts"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    },
    "summary": "Latest XBRL facts for a company",
    "tags": [
     "XBRL Facts"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  \"http://localhost:8080/v1/company/AAPL/facts?tag=EarningsPerShareDiluted\""
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/company/AAPL/facts\",\n    params={\"tag\": \"EarningsPerShareDiluted\"},\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nfor f in r.json()[\"facts\"]:\n    print(f[\"end_date\"], f[\"value\"], f[\"unit\"])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/company/AAPL/facts?tag=EarningsPerShareDiluted\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { facts } = await r.json();\nconsole.log(facts);"
     }
    ]
   }
  },
  "/v1/company/{ticker}/facts/{tag}": {
   "get": {
    "operationId": "factHistory",
    "parameters": [
     {
      "$ref": "#/components/parameters/ticker"
     },
     {
      "example": "Revenues",
      "in": "path",
      "name": "tag",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "company": {
           "$ref": "#/components/schemas/Company"
          },
          "count": {
           "type": "integer"
          },
          "facts": {
           "items": {
            "$ref": "#/components/schemas/Fact"
           },
           "type": "array"
          },
          "tag": {
           "type": "string"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Time series, oldest first"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Full time series for one XBRL concept",
    "tags": [
     "XBRL Facts"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  http://localhost:8080/v1/company/MSFT/facts/Revenues"
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/company/MSFT/facts/Revenues\",\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nhistory = r.json()[\"facts\"]  # oldest first"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/company/MSFT/facts/Revenues\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { facts } = await r.json(); // oldest first"
     }
    ]
   }
  },
  "/v1/company/{ticker}/filings": {
   "get": {
    "operationId": "companyFilings",
    "parameters": [
     {
      "$ref": "#/components/parameters/ticker"
     },
     {
      "description": "Form filter, e.g. `10-K`, `10-Q`, `8-K`, `4`",
      "in": "query",
      "name": "form",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "company": {
           "$ref": "#/components/schemas/Company"
          },
          "count": {
           "type": "integer"
          },
          "filings": {
           "items": {
            "$ref": "#/components/schemas/Filing"
           },
           "type": "array"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Filings, newest first"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Filing index for a company",
    "tags": [
     "Filings"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  \"http://localhost:8080/v1/company/TSLA/filings?form=10-K\""
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/company/TSLA/filings\",\n    params={\"form\": \"10-K\"},\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nprint(r.json()[\"filings\"][0][\"accession_number\"])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/company/TSLA/filings?form=10-K\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { filings } = await r.json();"
     }
    ]
   }
  },
  "/v1/events/8k": {
   "get": {
    "description": "One row per (filing, item code). Common items: `1.01` material agreement, `2.02` results of operations, `5.02` officer changes, `8.01` other events.",
    "operationId": "events8k",
    "parameters": [
     {
      "example": "2.02",
      "in": "query",
      "name": "item",
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "Filing-date floor, YYYY-MM-DD",
      "in": "query",
      "name": "since",
      "schema": {
       "format": "date",
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "count": {
           "type": "integer"
          },
          "events": {
           "items": {
            "$ref": "#/components/schemas/Event8K"
           },
           "type": "array"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Events, newest first"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    },
    "summary": "8-K material events across the universe",
    "tags": [
     "8-K Events"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  \"http://localhost:8080/v1/events/8k?item=2.02\u0026since=2026-07-01\""
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/events/8k\",\n    params={\"item\": \"2.02\", \"since\": \"2026-07-01\"},\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nfor e in r.json()[\"events\"]:\n    print(e[\"filing_date\"], e[\"ticker\"], e[\"item\"])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/events/8k?item=2.02\u0026since=2026-07-01\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { events } = await r.json();"
     }
    ]
   }
  },
  "/v1/events/enriched": {
   "get": {
    "description": "Structured events derived from 8-K filings by the enrichment stage: a closed event-type taxonomy, investor-impact materiality, a one-line headline, a \u003c=60-word summary, and named persons with roles and actions. Enriched once at ingest, served deterministic. Free and demo plans see the trailing 100 days (the response carries `history_limited_since` when clamped); paid plans include full history.",
    "operationId": "eventsEnriched",
    "parameters": [
     {
      "example": "officer_change",
      "in": "query",
      "name": "type",
      "schema": {
       "enum": [
        "results_announcement",
        "guidance_update",
        "officer_departure",
        "officer_appointment",
        "officer_change",
        "director_change",
        "material_agreement",
        "agreement_termination",
        "debt_financing",
        "equity_issuance",
        "dividend_or_buyback",
        "restructuring",
        "impairment",
        "compensation_arrangement",
        "delisting_notice",
        "auditor_change",
        "going_concern",
        "control_change",
        "shareholder_meeting",
        "bylaws_amendment",
        "cybersecurity_incident",
        "regulation_fd",
        "legal_proceeding",
        "exhibits_only",
        "other"
       ],
       "type": "string"
      }
     },
     {
      "in": "query",
      "name": "materiality",
      "schema": {
       "enum": [
        "high",
        "medium",
        "low"
       ],
       "type": "string"
      }
     },
     {
      "example": "AAPL",
      "in": "query",
      "name": "ticker",
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "Filing-date floor, YYYY-MM-DD. Free/demo plans are clamped to the trailing 100 days.",
      "in": "query",
      "name": "since",
      "schema": {
       "format": "date",
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "count": {
           "type": "integer"
          },
          "events": {
           "items": {
            "$ref": "#/components/schemas/EnrichedEvent"
           },
           "type": "array"
          },
          "history_limited_since": {
           "description": "Present on free/demo plans when the window was clamped",
           "format": "date",
           "type": "string"
          },
          "history_note": {
           "type": "string"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Enriched events, newest filing first"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    },
    "summary": "LLM-enriched 8-K events: classified, summarized, persons extracted",
    "tags": [
     "8-K Events"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  \"http://localhost:8080/v1/events/enriched?type=officer_change\u0026materiality=high\""
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/events/enriched\",\n    params={\"type\": \"officer_change\", \"materiality\": \"high\"},\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nfor e in r.json()[\"events\"]:\n    print(e[\"filing_date\"], e[\"ticker\"], e[\"headline\"])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/events/enriched?type=officer_change\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { events } = await r.json();\nfor (const e of events) console.log(e.filing_date, e.ticker, e.headline);"
     }
    ]
   }
  },
  "/v1/insiders/{ticker}/transactions": {
   "get": {
    "description": "Parsed from ownership XML. `transaction_code`: P purchase, S sale, A award, M option exercise, G gift, F tax withholding.",
    "operationId": "insiderTransactions",
    "parameters": [
     {
      "$ref": "#/components/parameters/ticker"
     },
     {
      "$ref": "#/components/parameters/limit"
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "company": {
           "$ref": "#/components/schemas/Company"
          },
          "count": {
           "type": "integer"
          },
          "transactions": {
           "items": {
            "$ref": "#/components/schemas/InsiderTransaction"
           },
           "type": "array"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Transactions, newest first"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Form 4 insider transactions for a company",
    "tags": [
     "Insiders"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  http://localhost:8080/v1/insiders/NVDA/transactions"
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.get(\n    \"http://localhost:8080/v1/insiders/NVDA/transactions\",\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nfor t in r.json()[\"transactions\"]:\n    print(t[\"owner_name\"], t[\"transaction_code\"], t[\"shares\"])"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\n  \"http://localhost:8080/v1/insiders/NVDA/transactions\",\n  { headers: { Authorization: `Bearer ${FJ_KEY}` } },\n);\nconst { transactions } = await r.json();"
     }
    ]
   }
  },
  "/v1/webhooks/sec-events": {
   "get": {
    "operationId": "listWebhooks",
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "properties": {
          "count": {
           "type": "integer"
          },
          "webhooks": {
           "items": {
            "$ref": "#/components/schemas/WebhookSubscription"
           },
           "type": "array"
          }
         },
         "type": "object"
        }
       }
      },
      "description": "Your subscriptions (secrets omitted)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    },
    "summary": "List your webhook subscriptions",
    "tags": [
     "Webhooks"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -H \"Authorization: Bearer $FJ_KEY\" \\\n  http://localhost:8080/v1/webhooks/sec-events"
     }
    ]
   },
   "post": {
    "description": "New matching 8-K events are POSTed to your URL as they are ingested. Each delivery carries `X-FilingsJSON-Signature: hex(HMAC-SHA256(secret, body))` — the secret is returned **once**, at creation. Deliveries retry 3× and are idempotent per (subscription, filing, item).",
    "operationId": "createWebhook",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "items": {
          "description": "comma-separated item filter, e.g. `2.02,5.02` (empty = all)",
          "type": "string"
         },
         "tickers": {
          "description": "comma-separated ticker filter (empty = all)",
          "type": "string"
         },
         "url": {
          "format": "uri",
          "type": "string"
         }
        },
        "required": [
         "url"
        ],
        "type": "object"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookSubscription"
        }
       }
      },
      "description": "Subscription created (secret shown once)"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    },
    "summary": "Subscribe to SEC events",
    "tags": [
     "Webhooks"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -X POST -H \"Authorization: Bearer $FJ_KEY\" \\\n  -d '{\"url\":\"https://example.com/hooks/sec\",\"items\":\"2.02,5.02\",\"tickers\":\"AAPL,TSLA\"}' \\\n  http://localhost:8080/v1/webhooks/sec-events"
     },
     {
      "label": "Python",
      "lang": "python",
      "source": "import requests\n\nr = requests.post(\n    \"http://localhost:8080/v1/webhooks/sec-events\",\n    json={\"url\": \"https://example.com/hooks/sec\", \"items\": \"2.02,5.02\"},\n    headers={\"Authorization\": f\"Bearer {FJ_KEY}\"},\n)\nsecret = r.json()[\"secret\"]  # store it — shown once\n\n# verifying a delivery:\nimport hmac, hashlib\n\ndef verify(body: bytes, signature: str) -\u003e bool:\n    want = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(want, signature)"
     },
     {
      "label": "JavaScript",
      "lang": "javascript",
      "source": "const r = await fetch(\"http://localhost:8080/v1/webhooks/sec-events\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${FJ_KEY}` },\n  body: JSON.stringify({ url: \"https://example.com/hooks/sec\", items: \"2.02\" }),\n});\nconst { secret } = await r.json(); // store it — shown once\n\n// verifying a delivery (Node):\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\nconst verify = (body, sig) =\u003e {\n  const want = createHmac(\"sha256\", secret).update(body).digest(\"hex\");\n  return timingSafeEqual(Buffer.from(want), Buffer.from(sig));\n};"
     }
    ]
   }
  },
  "/v1/webhooks/sec-events/{id}": {
   "delete": {
    "operationId": "deleteWebhook",
    "parameters": [
     {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Deactivated"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Deactivate a webhook subscription",
    "tags": [
     "Webhooks"
    ],
    "x-codeSamples": [
     {
      "label": "curl",
      "lang": "shell",
      "source": "curl -X DELETE -H \"Authorization: Bearer $FJ_KEY\" \\\n  http://localhost:8080/v1/webhooks/sec-events/1"
     }
    ]
   }
  }
 },
 "security": [
  {
   "bearerAuth": []
  },
  {
   "apiKeyAuth": []
  }
 ],
 "servers": [
  {
   "description": "production",
   "url": "https://filingsjson.com"
  }
 ],
 "tags": [
  {
   "description": "Tracked filer universe",
   "name": "Companies"
  },
  {
   "description": "Normalized financial facts from company XBRL filings",
   "name": "XBRL Facts"
  },
  {
   "description": "Filing index per company",
   "name": "Filings"
  },
  {
   "description": "Material-event stream, one row per item code",
   "name": "8-K Events"
  },
  {
   "description": "Form 4 insider transactions",
   "name": "Insiders"
  },
  {
   "description": "Push delivery of new SEC events",
   "name": "Webhooks"
  },
  {
   "description": "Self-serve key issuance",
   "name": "Keys"
  }
 ]
}