{"service":"sec-alerts","version":"1.0.0","endpoints":{"watch_registration":{"method":"POST","path":"/toll/secalerts/watch","price_usd":0.005,"price_status":"PROPOSED-UNRULED","request":{"ciks":"array of CIK strings, 1-10 digits each, at most 25 — provide ciks and/or tickers","tickers":"array of ticker symbols, at most 25, resolved to CIKs at registration; an unresolvable ticker is a free 400 unknown_ticker","forms":"optional array of form strings, at most 20; absent/null/empty = all forms; a filter matches the exact form or its base form","amendments_only":"optional boolean, default false; filters filing events only, never deletion flags","include_deletions":"optional boolean, default false; deletion flags only under the provenance rule in deletion_scope"},"response":{"answer":"{watch_id, created_at, initial_cursor} — watch_id is a bearer credential (see ownership)","watch":"the stored rule echo plus payer_bound:true","price_charged_usd":"the charged price; its price_status field carries the PROPOSED-UNRULED mark wherever the registration price is quoted"}},"alerts_poll":{"method":"GET","path":"/toll/secalerts/alerts","price_usd":0.01,"price_status":"RULED","query":{"watch_id":"required — the bearer credential issued at registration","cursor":"optional opaque cursor; absent = the watch initial cursor. A cursor bound to a different watch is a free 400 bad_cursor."},"response":{"answer":"{watch_id, delivered_count, new_filing_count, amendment_count, deletion_count}","events":"[event] ordered by (event_at, accession, kind_ordinal) ascending — filing-class events before a deletion_flag at an identical (event_at, accession) — at most 200 per poll","next_cursor":"opaque cursor at the last delivered event, or the input cursor when zero were delivered","redelivered":"present and true when the response is re-served free from the delivery record (see cursor.retention)"}},"watch_status":{"method":"GET","path":"/toll/secalerts/watch/status","price_usd":0,"note":"free, watch_id-gated, counts only"},"watch_delete":{"method":"POST","path":"/toll/secalerts/watch/delete","price_usd":0,"note":"free, watch_id-gated; refund records are retained"},"preflights":"every paid op has a free preflight twin at the same path plus /preflight; the poll preflight returns the pending-event count only"},"watch_rule":{"caps":{"ciks_per_watch":25,"tickers_per_watch":25,"distinct_ciks_after_resolution":50,"forms_per_watch":20,"active_watches_per_payer":100},"immutable":"no update op exists in v1; changing rules = delete (free) + re-register"},"event":{"types":["new_filing","amendment","deletion_flag"],"fields":"event_type, event_at, accession, cik, ticker, form, base_form, is_amendment, accepted_at, filing_date, first_seen_at, seeded, source, deletion_provenance; deletion_flag events additionally carry removed_from_submissions:true, removal_detected_at (= event_at) and deletion_provenance weekly_index_reconciliation"},"filing_record":{"accession":"SEC accession number — unique, never recycled; the store dedupe key","cik":"10-digit zero-padded CIK","form":"form as filed (e.g. 8-K, 8-K/A)","base_form":"form with any trailing /A stripped","is_amendment":"true when form is a /A variant","accepted_at":"SEC acceptance timestamp from EDGAR","filing_date":"SEC filingDate","first_seen_at":"first_seen_at is ExchangeRebel's own detection timestamp — the moment this service first recorded the filing in its append-only store. The SEC publishes no availability timestamp, so no seller's first-seen time can be anything other than their own observation. For a filer's first-ever touch, the store is seeded from the filer's returned history and first_seen_at is the seed time (records carry seeded:true).","seeded":"true when recorded from a filer history seed; seeded records never produce events","source":"the filer data.sec.gov submissions URL the record was captured from"},"cursor":{"form":"opaque base64url JSON {v:2, watch:<watch_id hash>, ts, acc, ord} — ord is the event-kind ordinal of the position (filing-class 0 sorts before deletion_flag 1 at an identical (ts, acc)); callers must treat cursors as opaque. Version-1 cursors (the pre-fix pair position) are refused as invalid (free 400 bad_cursor); this service is pre-release, so no live v1 cursors exist","retention":"a successful poll writes a delivery record keyed by (watch_id, input cursor); re-polling the same cursor within 7 days re-serves that record verbatim and free; after 7 days a re-poll is a fresh paid poll","advancement":"a cursor advances only on successful delivery; settled-but-zero and settled-but-failed polls leave it unmoved and write exactly one refund intent"},"ownership":"Your watch_id is a bearer credential: in v1, possession of a watch_id is read access to that watch's alerts view. There is no separate secret, no rotation, and no recovery for a lost watch_id. If a watch_id leaks, delete the watch (free) and register a new one.","first_seen_disclosure":"first_seen_at is ExchangeRebel's own detection timestamp — the moment this service first recorded the filing in its append-only store. The SEC publishes no availability timestamp, so no seller's first-seen time can be anything other than their own observation. For a filer's first-ever touch, the store is seeded from the filer's returned history and first_seen_at is the seed time (records carry seeded:true).","deletion_scope":"Deletion flags are issued only for removals confirmed by the weekly full-index reconciliation: a deletion_flag event is produced only from a record whose provenance marks it weekly-index-reconciliation-sourced. Removals noticed when a single filer's submissions record is re-read are never issued as deletion alerts by this service. Until the weekly reconciliation is wired to the live store, deletion flags do not fire in production.","seeded_records":"Filings already in the store when your watch is registered never alert: a watch reports only filings first seen after it was created, and records seeded from a filer's history on first touch (seeded:true) never produce events.","crossover":"Honest crossover: polls cost $0.01 (ruled price) per delivered alerts view. A caller whose watches deliver about 500 events a month is spending about $5.00 a month here — the price of Datamule's $5/month subscription — and continuous, high-volume watchers are better served by that subscription. This service is built for episodic, task-driven agent queries: register a watch, poll it when the task needs the answer, and pay only for delivered views.","envelope":{"v":1,"service":"sec-alerts","as_of":"2026-11-14T14:49:33.186Z","source":"sec-alerts service configuration","grade":"derived","max_age_seconds":300,"changes":{"supported":true,"endpoint":"/toll/secalerts/alerts","price_usd":0.01,"basis":"standing watch + cursor over the append-only first-seen store keyed by accession number; first_seen_at = our detection time (the SEC publishes no availability timestamp)"}}}