Filings Desk API

Mint a key at /dashboard/api-keys, then post a ticker.

curl -X POST https://filings.ounie.com/api/diff \
  -H "Authorization: Bearer flg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"ticker":"AAPL","section":"risk_factors"}'

Every verb accepts ticker or cik. A CIK may be passed with or without leading zeros; it is padded to ten digits internally, which is what EDGAR requires.

• Your app key — Authorization: Bearer flg_live_…, minted at /dashboard/api-keys. Up to five active at a time; the raw token is shown once.
• The Ounie master key — your ounie.com developer key (ounie_live_…) works here too, once you enable Use across Ounie apps in your Ounie settings. One key, the whole fleet.
• A browser session — the shared .ounie.com cookie authenticates the same endpoints for the dashboard.

Clients that cannot set a header may pass ?api_key=flg_live_… on any endpoint. A bad key returns 401 — never a redirect, which an agent cannot follow.

Every filing EDGAR holds for one company, newest first.

{
  "company": { "cik": "0000320193", "name": "Apple Inc.", "tickers": ["AAPL"], … },
  "filings": [
    { "accession": "0000320193-25-000079", "form": "10-K",
      "filedAt": "2025-10-31", "reportDate": "2025-09-27",
      "documentUrl": "https://www.sec.gov/Archives/edgar/data/320193/…/aapl-20250927.htm",
      "filingIndexUrl": "…", "items": [], "isInlineXbrl": true,
      "submissionBytes": 9392337 }
  ],
  "total": 41,
  "moreAvailable": true
}

• submissionBytes is EDGAR's own size field and it counts the whole submission, exhibits included — it overstates the primary document by five to twelve times. It is named for what it is and nothing is sized off it.
• moreAvailableis true when older filings exist beyond EDGAR's ~1,000-entry recent block and were not fetched. It is there so that “no filings before 2015” is never mistaken for a fact about the company.

Annual figures read from the company's own XBRL, via EDGAR's company-concept endpoint (~18 KB per concept, rather than the 4–8 MB full fact set).

{
  "series": [
    { "metric": "revenue", "label": "Revenue",
      "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
      "triedTags": ["RevenueFromContract…", "Revenues", …],
      "unit": "USD", "tagged": true,
      "points": [ { "fiscalYear": 2025, "periodEnd": "2025-09-27",
                    "value": 416161000000, "form": "10-K",
                    "filed": "2025-10-31", "accession": "0000320193-25-000079" } ] }
  ],
  "notTagged": ["gross_profit"]
}

A metric this filer does not tag appears in notTagged, by name. It is never returned as a zero and never silently dropped. If none of the requested metrics are tagged, the call is thin and refunds in full.

One section of an annual filing compared against the previous annual filing, paragraph by paragraph.

{
  "section": "risk_factors",
  "sectionLabel": "Item 1A — Risk factors",
  "from": { "accession": "0000320193-24-000123", "filedAt": "2024-11-01",
            "url": "https://www.sec.gov/Archives/…", "words": 11284 },
  "to":   { "accession": "0000320193-25-000079", "filedAt": "2025-10-31",
            "url": "https://www.sec.gov/Archives/…", "words": 11190 },
  "counts": { "added": 3, "removed": 1, "changed": 9,
              "unchanged": 42, "softened": 4, "hardened": 2 },
  "identical": false,
  "items": [
    { "kind": "added", "heading": "The Company's business…", "text": "…", "words": 214 },
    { "kind": "changed", "similarity": 0.78, "toneShift": "softened",
      "previous": "…", "text": "…",
      "toneEvidence": { "hedgeDensityBefore": 4.1, "hedgeDensityAfter": 5.4,
                        "severityDensityBefore": 3.9, "severityDensityAfter": 3.2 } }
  ],
  "itemsTruncated": false,
  "summary": { "headline": "…", "paragraphs": ["…"], "model": "openai/gpt-5-nano" }
}

• Paragraphs are matched by similarity, not position. Filings are re-paginated every year; positional comparison would report one insertion at the top as a rewrite of everything below it.
• ≥ 0.985 is unchanged; ≥ 0.55 is the same paragraph reworded; anything below has no counterpart and is added or removed.
• Up to 60 items come back in full; itemsTruncated says when there were more. The counts always describe everything, not just what was returned.
• The model never performs the comparison.It is handed the comparison's output and asked to describe it, so it cannot introduce a change that is not there. summary: false removes it entirely.
• Only 10-Kfilings are compared. A 10-Q carries an abbreviated “material changes” item that is not comparable to an annual one.

A modern 10-K is 220,000 to 1,400,000 characters of text. Two of them will not fit in a prompt, so the section is cut out first — and the cut has to be right, because a comparison of the wrong section is fluent, confident and false.

The widest-gap rule.For every “Item 1B. Unresolved Staff Comments” heading, take the last “Item 1A. Risk Factors” before it, and keep the pair furthest apart. The first match in a filing is almost always the table of contents, and taking the last fails outright on filings whose final “Item 1A” falls after their final Item 1B. Non-breaking and zero-width characters are stripped before matching, since they sit inside the heading in most filings.

The extraction is then checked — long enough to be a section, and reading like the section it claims to be. When the check fails you get a reason and no charge:

On a reworded paragraph, toneShift is one of softened, hardened or neutral. It means exactly one thing: hedging density moved relative to severity density.

• Hedges — may, might, could, generally, typically, believe, expect, approximately, certain…
• Severity — material, significant, substantial, adverse, severe, harm, loss, failure, cannot…
• Both are counted per hundred words and returned in toneEvidence, so you can re-derive the label yourself.

A call that could not produce its artifact is never billed. Credits are reserved at submit and returned pool by pool, exactly as they were drawn. On REST this is a 422 carrying charged: false.

A diff that finds zero changesis not thin. “The risk language did not move this year” is a real finding and is billed in full.

EDGAR is free and public, so the index and facts verbs have no external dependency that can refuse them. The one metered upstream in this app is the model that writes a diff's summary paragraph.

A scheduled probe checks that upstream with a real request — never a read, because a provider whose account is unpaid keeps answering reads perfectly while refusing every write. While it is refusing, a diff that asked for a summary is refused up front with a 503, before any price is quoted and before any credits are reserved. Nothing is charged, and no reserve/refund pair appears in your ledger.

The other two verbs keep working throughout, and so does {"summary": false}.

Reading work you already paid for is free, forever.

GET /api/filings?limit=20&verb=diff     # your run history
GET /api/runs/<run_id>                  # one run, with its full result

Streamable HTTP at /api/mcp, legacy SSE at /api/sse. Works with Claude, Cursor, ChatGPT, the AI SDK and the Ounie AI Team — which cannot set static headers on a manual HTTP entry, so the key rides the URL.

Endpoint  https://filings.ounie.com/api/mcp   (legacy SSE: /api/sse)
Auth      Authorization: Bearer flg_live_…
          …or https://filings.ounie.com/api/mcp?api_key=flg_live_…

A tool call that cannot be covered fails with insufficient_credits and a link to top up. An agent can never overdraw.

Agents with no Ounie account pay in USDC on Base. One endpoint takes all three verbs, and the price is computed from your payload rather than baked into the route — so the keyless rail and the credit rail can never disagree about what a call costs.

POST https://filings.ounie.com/api/x402/filings
{"verb":"facts","ticker":"TSLA","metrics":["revenue","net_income"]}

→ 402  {"x402Version":1,"accepts":[{"scheme":"exact","network":"base",
         "maxAmountRequired":"60000", …}]}
→ retry with  X-Payment: <signed authorization>
→ 200  {"payment":{"tx_hash":"0x…"}, "series":[…]}

• Two gates. Anything knowable from the request alone — an unknown verb, a malformed ticker, a metric outside the enum — returns 4xx with no price in the body. You are never asked to sign for work that cannot succeed.
• Verify, run, then settle. An on-chain settlement is final and there is no refund path, so a call that produced nothing is refused before the money moves.
• All or nothing. The exact scheme compares the signed value, so a reduced settlement would be refused after the work is done. A diff whose summary could not be written returns 402 partial_delivery without settling — retry, or ask for summary: false.

That last one is deliberate. EDGAR returns no 429 and publishes no throttle header — its documented failure mode is a silent block of the user agent, which is unrecoverable. The absence of an error is not headroom.

• No score, rating or outlook. There is no number in this product that summarises whether a company is doing well.
• No price or market data. EDGAR holds filings, not quotes.
• No full-text search across filers.EDGAR's full-text index effectively starts in 2001, filters on the root form so exhibits come back alongside the document you asked for, and saturates its total at 10,000. It is not shipped rather than shipped with caveats nobody reads.
• No 10-Q comparison.A quarterly “material changes” item is not the annual set.

Credits are managed on your Ounie account — top up here. Verb names and labels: filings = Filings index · facts = XBRL facts · diff = Risk diff.