Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Connect to a WebSocket to receive corporate disclosures in real time, milliseconds after they are ingested from EDGAR. No API key required — the stream is publicly accessible.
The stream replays your missed messages on reconnect. Pass ?last_id=<id> to resume from where you left off.

​
Endpoint

wss://api.ivory.finance/v1/stream/filings
Query parameters
ParameterTypeDefaultDescription
last_idstring$Stream cursor. $ = live messages only. Pass the last received id to replay missed events on reconnect.

​
Message Format

Every message is a JSON object with a type field.

​
Filing event

Emitted for each new corporate disclosure ingested. 
{
  "type": "filing",
  "id": "1740123456789-0",
  "accession_number": "0000320193-26-000010",
  "cik": "0000320193",
  "company_name": "Apple Inc.",
  "form_type": "8-K",
  "is_amendment": "0",
  "published_at": "2026-02-21T04:30:00+00:00",
  "link": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000010/0000320193-26-000010-index.htm"
}

​
Heartbeat

Sent every ~5 seconds when the stream is idle. Use this to detect stale connections. 
{ "type": "heartbeat" }

​
Code Examples

const ws = new WebSocket("wss://api.ivory.finance/v1/stream/filings");

ws.onopen = () => console.log("Connected to live filings stream");

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.type === "filing") {
    console.log(`${msg.company_name} filed ${msg.form_type} — ${msg.link}`);
    // save last_id for reconnect
    localStorage.setItem("lastFilingId", msg.id);
  }
};

ws.onclose = () => {
  // Reconnect from last known position
  const lastId = localStorage.getItem("lastFilingId") ?? "$";
  const reconnect = new WebSocket(
    `wss://api.ivory.finance/v1/stream/filings?last_id=${lastId}`
  );
};

​
Reconnection Pattern

The stream uses Valkey Streams under the hood. Each message has a unique monotonic id (<milliseconds>-<sequence>). To resume after a disconnect without missing or duplicating events:
  1. Store the last received id client-side.
  2. Reconnect with ?last_id=<stored_id>.
  3. The server replays all messages after that ID, then switches to live delivery.
The stream retains the last 10,000 disclosures. For older history use GET /v1/filings/recent.