{"openapi":"3.1.0","info":{"title":"FilingPulse API","description":"Real-time normalized SEC EDGAR filings: Form 3/4/5 insider ownership filings and 8-K corporate events, one stable JSON schema. FilingPulse is data infrastructure — it reports what was filed with the SEC and provides no investment advice, signals, or recommendations.","contact":{"name":"FilingPulse","url":"https://filingpulse.io/","email":"raxcuh06@gmail.com"},"version":"0.1.0"},"servers":[{"url":"https://api.filingpulse.io","description":"Production"}],"paths":{"/":{"get":{"tags":["meta"],"summary":"Service pointer","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/schema":{"get":{"tags":["meta"],"summary":"Machine-readable schema v1 contract","description":"The full normalized-schema contract as JSON: objects, field types, design rules,\nthe list-response envelope, and the transaction-code table. Static and versioned —\nsafe to fetch at build time for codegen or contract tests. No authentication required.","operationId":"schema_v1_schema_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/health":{"get":{"tags":["meta"],"summary":"Dataset counts and freshness","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"tags":["account"],"summary":"Your key's tier, quota, and usage this month","description":"Introspection for the calling key: tier, monthly quota, requests used and\nremaining this month, per-minute rate limit, and webhook slots. The numbers come\nfrom the same counters the limits are enforced with (UTC calendar month, resets at\n00:00 UTC on the 1st — `quota_resets_at` is the exact instant), so they cannot\ndisagree with a 429 you just received. Calling this endpoint does NOT count against\nthe monthly quota; it does count toward the per-minute rate limit.\n`webhooks.limit` is null on tiers with unlimited subscriptions.","operationId":"usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit exceeded (Retry-After header). This endpoint never consumes the monthly quota, so it keeps working after a quota 429."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/insider-trades":{"get":{"tags":["filings"],"summary":"List insider ownership filings (Forms 3/4/5)","operationId":"insider_trades_v1_insider_trades_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Issuer ticker symbol, exactly as filed","title":"Ticker"},"description":"Issuer ticker symbol, exactly as filed"},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{1,10}$"},{"type":"null"}],"description":"Issuer CIK, digits only","title":"Cik"},"description":"Issuer CIK, digits only"},{"name":"owner_cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{1,10}$"},{"type":"null"}],"description":"Reporting owner (insider) CIK, digits only — one person or entity's filings across every issuer","title":"Owner Cik"},"description":"Reporting owner (insider) CIK, digits only — one person or entity's filings across every issuer"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(3|3/A|4|4/A|5|5/A)$"},{"type":"null"}],"description":"3, 4, or 5, or the /A variant for amendments only (Forms 3/5 are live-forward since 2026-09-23)","title":"Form Type"},"description":"3, 4, or 5, or the /A variant for amendments only (Forms 3/5 are live-forward since 2026-09-23)"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only filings filed on/after this date","title":"Since"},"description":"Only filings filed on/after this date"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only filings filed on/before this date — with since=, a fixed reproducible window","title":"Until"},"description":"Only filings filed on/before this date — with since=, a fixed reproducible window"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Rows per page (max 200)","default":50,"title":"Limit"},"description":"Rows per page (max 200)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Pagination offset (max 10,000)","default":0,"title":"Offset"},"description":"Pagination offset (max 10,000)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/insider-trades/{accession}":{"get":{"tags":["filings"],"summary":"One filing by accession number","operationId":"insider_trade_v1_insider_trades__accession__get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"accession","in":"path","required":true,"schema":{"type":"string","title":"Accession"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"404":{"description":"No resource with that identifier (or not owned by this key)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signup":{"post":{"tags":["signup"],"summary":"Get an API key: free tier by email, paid tiers via Stripe Checkout","operationId":"signup_endpoint_v1_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"409":{"description":"This email already has an active free key."},"429":{"description":"Too many signup attempts from this address."},"503":{"description":"Signups (or paid signups) not currently enabled."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/registrations":{"get":{"tags":["registrations"],"summary":"List S-1/IPO registration lifecycle events","operationId":"registrations_v1_registrations_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"stage","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(registration|amendment|effectiveness|prospectus)$"},{"type":"null"}],"description":"Lifecycle stage: registration, amendment, effectiveness, or prospectus","title":"Stage"},"description":"Lifecycle stage: registration, amendment, effectiveness, or prospectus"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(S-1|S-1/A|F-1|F-1/A|EFFECT|424B1|424B4)$"},{"type":"null"}],"description":"Exact form type, e.g. S-1 or 424B4","title":"Form Type"},"description":"Exact form type, e.g. S-1 or 424B4"},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{1,10}$"},{"type":"null"}],"description":"Issuer CIK, digits only","title":"Cik"},"description":"Issuer CIK, digits only"},{"name":"file_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[\\d-]{1,20}$"},{"type":"null"}],"description":"SEC file number, e.g. 333-296288 — follows one offering across stages","title":"File Number"},"description":"SEC file number, e.g. 333-296288 — follows one offering across stages"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only events filed on/after this date","title":"Since"},"description":"Only events filed on/after this date"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only events filed on/before this date","title":"Until"},"description":"Only events filed on/before this date"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Rows per page (max 200)","default":50,"title":"Limit"},"description":"Rows per page (max 200)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Pagination offset (max 10,000)","default":0,"title":"Offset"},"description":"Pagination offset (max 10,000)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/registrations/{accession}":{"get":{"tags":["registrations"],"summary":"One registration event by accession number","operationId":"registration_v1_registrations__accession__get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"accession","in":"path","required":true,"schema":{"type":"string","title":"Accession"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"404":{"description":"No resource with that identifier (or not owned by this key)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List your webhook subscriptions","operationId":"list_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."}},"security":[{"ApiKeyAuth":[]}]},"post":{"tags":["webhooks"],"summary":"Create a webhook subscription (secret shown once)","operationId":"create_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"403":{"description":"Active-webhook limit for your tier reached."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/webhooks/{sub_id}":{"delete":{"tags":["webhooks"],"summary":"Deactivate a webhook subscription","operationId":"delete_webhook_v1_webhooks__sub_id__delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"integer","title":"Sub Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"404":{"description":"No resource with that identifier (or not owned by this key)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{sub_id}/deliveries":{"get":{"tags":["webhooks"],"summary":"Delivery log for a subscription","operationId":"webhook_deliveries_v1_webhooks__sub_id__deliveries_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"integer","title":"Sub Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Rows returned, newest first (max 200)","default":50,"title":"Limit"},"description":"Rows returned, newest first (max 200)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"404":{"description":"No resource with that identifier (or not owned by this key)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events":{"get":{"tags":["events"],"summary":"List 8-K corporate events","operationId":"events_v1_events_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"item","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d\\.\\d{2}$"},{"type":"null"}],"description":"8-K item code, e.g. 2.02","title":"Item"},"description":"8-K item code, e.g. 2.02"},{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}],"description":"Issuer ticker symbol, resolved to a CIK via this dataset's Form 4 filings (8-K headers carry no ticker); 404 if no Form 4 has carried it","title":"Ticker"},"description":"Issuer ticker symbol, resolved to a CIK via this dataset's Form 4 filings (8-K headers carry no ticker); 404 if no Form 4 has carried it"},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{1,10}$"},{"type":"null"}],"description":"Issuer CIK, digits only","title":"Cik"},"description":"Issuer CIK, digits only"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only events filed on/after this date","title":"Since"},"description":"Only events filed on/after this date"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Only events filed on/before this date","title":"Until"},"description":"Only events filed on/before this date"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Rows per page (max 200)","default":50,"title":"Limit"},"description":"Rows per page (max 200)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Pagination offset (max 10,000)","default":0,"title":"Offset"},"description":"Pagination offset (max 10,000)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid X-API-Key."},"429":{"description":"Per-minute rate limit or monthly quota exceeded. Per-minute 429s carry Retry-After; quota 429s carry X-Quota-Limit / X-Quota-Used. Quotas reset at 00:00 UTC on the 1st."},"404":{"description":"No resource with that identifier (or not owned by this key)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SignupRequest":{"properties":{"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier","default":"free"},"ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ref"}},"type":"object","required":["email"],"title":"SignupRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookCreate":{"properties":{"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events","default":["form4","8k"]},"filters":{"additionalProperties":true,"type":"object","title":"Filters","default":{}}},"type":"object","required":["url"],"title":"WebhookCreate"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"API key, e.g. fp_xxxxx. All /v1 endpoints except /v1/health and /v1/schema require one.","in":"header","name":"X-API-Key"}}},"tags":[{"name":"filings","description":"Form 3/4/5 insider ownership filings, normalized to schema v1."},{"name":"events","description":"8-K corporate events classified by official item code."},{"name":"registrations","description":"S-1/IPO registration lifecycle: registration statements, amendments, effectiveness notices, and priced prospectuses, threaded by SEC file number."},{"name":"webhooks","description":"Push delivery of new filings as they land, HMAC-signed."},{"name":"meta","description":"Service health and the machine-readable schema contract. No authentication required."},{"name":"account","description":"Key introspection: your tier, quota, and usage this month — the same counters the limits are enforced with. Requires your API key."},{"name":"signup","description":"Self-serve key issuance: free tier by email, paid tiers via Stripe Checkout. No authentication required."}]}