{"openapi":"3.1.0","info":{"title":"DilutionRisk API","version":"1.0.0","description":"Read-only access to ASX company snapshots, dilution instruments, filings, ledger history, screener metrics, market quotes and revision-pinned research. Public data is served from the revision-pinned Hugging Face Dataset, Bucket and Space behind stable website routes.","contact":{"name":"DilutionRisk","url":"https://www.dilutionrisk.com"}},"servers":[{"url":"https://www.dilutionrisk.com","description":"Production"}],"tags":[{"name":"Companies","description":"Company and instrument universe."},{"name":"Documents","description":"ASX filing metadata and derived artifacts."},{"name":"Research","description":"Revision-pinned Gradio research facade."},{"name":"Updates","description":"Recent dilution-risk filings and material changes."},{"name":"Analytics","description":"Dilution ledger and screener views."},{"name":"Market data","description":"Live ASX quote data."}],"paths":{"/api/companies":{"get":{"tags":["Companies"],"operationId":"listCompanies","summary":"List supported companies","description":"Returns supported ASX issuers from the public Hugging Face dataset.","parameters":[{"$ref":"#/components/parameters/Exchange"},{"name":"limit","in":"query","description":"Maximum number of companies to return.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}}],"responses":{"200":{"description":"Supported companies","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanyListItem"}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/company":{"get":{"tags":["Companies"],"operationId":"getCompany","summary":"Get a company snapshot","description":"Returns the latest company snapshot or a historical snapshot for a requested date. Optional computed metrics provide server-side worst-case and treasury-stock-method estimates.","parameters":[{"$ref":"#/components/parameters/Ticker"},{"$ref":"#/components/parameters/Exchange"},{"name":"as_of_date","in":"query","description":"Historical snapshot date in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"computed","in":"query","description":"Include server-computed worst-case and treasury-stock-method metrics.","schema":{"oneOf":[{"type":"boolean"},{"type":"integer","enum":[0,1]}],"default":false}}],"responses":{"200":{"description":"Company snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySnapshot"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/documents":{"get":{"tags":["Documents"],"operationId":"listDocuments","summary":"List ASX filings","description":"Returns a cursor-paginated filing feed with public Hugging Face artifact resolvers and original ASX source links.","parameters":[{"$ref":"#/components/parameters/Exchange"},{"$ref":"#/components/parameters/OptionalTicker"},{"name":"instrument_id","in":"query","description":"Canonical instrument identifier, for example ASX:BHP.","schema":{"type":"string","example":"ASX:BHP"}},{"name":"doc_type","in":"query","description":"Filter by classified filing type.","schema":{"type":"string","example":"Appendix 2A"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"cursor","in":"query","description":"Opaque next_cursor value returned by the previous page.","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["available_desc","available_asc"],"default":"available_desc"}}],"responses":{"200":{"description":"Paginated filings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPage"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/documents/preview":{"get":{"tags":["Documents"],"operationId":"previewDocumentMarkdown","summary":"Read a markdown artifact","description":"Returns an approved public Hugging Face Bucket markdown object through a CORS-safe same-origin facade.","parameters":[{"name":"hf","in":"query","required":true,"description":"Public hash-addressed Hugging Face Bucket object key.","schema":{"type":"string","example":"artifacts/v1/asx/BHP/03000000/markdown/parser/hash.md"}}],"responses":{"200":{"description":"Markdown content","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/research":{"post":{"tags":["Research"],"operationId":"searchResearchEvidence","summary":"Search company metrics and filing evidence","description":"Calls the public read-only Gradio company and document search functions server-side. Returns only results from one pinned Dataset revision and exposes no HF token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":120},"ticker":{"type":"string","pattern":"^[A-Z0-9]{2,6}$"},"doc_type":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"Revision-pinned company and filing matches","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/updates":{"get":{"tags":["Updates"],"operationId":"listUpdates","summary":"List recent dilution-risk signals","description":"Returns recent Appendix 2A, 3B, and 4C filings plus material fully-diluted ratio and cash-runway changes when structured extraction data is available.","parameters":[{"$ref":"#/components/parameters/Exchange"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":30}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":120}}],"responses":{"200":{"description":"Recent signals","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Update"}}}}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ledger":{"get":{"tags":["Analytics"],"operationId":"getDilutionLedger","summary":"Get dilution history","description":"Builds an ordered time series from register instrument events in the public HF dataset.","parameters":[{"$ref":"#/components/parameters/Ticker"},{"$ref":"#/components/parameters/Exchange"},{"name":"bucket","in":"query","schema":{"type":"string","enum":["quarter","month"],"default":"quarter"}}],"responses":{"200":{"description":"Dilution history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ledger"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stats":{"get":{"tags":["Companies"],"operationId":"getSiteStats","summary":"Get dataset coverage stats","description":"Returns public coverage counts (companies tracked, filings processed, filings discovered in the last 24 hours) sourced from the published dataset.","responses":{"200":{"description":"Coverage stats","content":{"application/json":{"schema":{"type":"object","properties":{"companies_tracked":{"type":["integer","null"]},"filings_processed":{"type":["integer","null"]},"filings_last_24h":{"type":["integer","null"]},"dataset_revision":{"type":"string"}}}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/screener":{"get":{"tags":["Analytics"],"operationId":"getScreener","summary":"Get dilution screener rows","description":"Returns one compact precomputed screener snapshot through the selected provider, without browser per-company fan-out.","parameters":[{"$ref":"#/components/parameters/Exchange"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":10,"maximum":1000,"default":300}}],"responses":{"200":{"description":"Screener rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screener"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/quote":{"get":{"tags":["Market data"],"operationId":"getQuote","summary":"Get an ASX quote","description":"Returns a five-minute cached quote from the ASX market-data endpoint.","parameters":[{"$ref":"#/components/parameters/Ticker"},{"$ref":"#/components/parameters/Exchange"}],"responses":{"200":{"description":"Latest quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"parameters":{"Exchange":{"name":"exchange","in":"query","description":"Exchange code. ASX has full dataset coverage; NZX is accepted and returns empty results until its corpus is published.","schema":{"type":"string","enum":["ASX","NZX"],"default":"ASX"}},"Ticker":{"name":"ticker","in":"query","required":true,"description":"ASX ticker, case-insensitive.","schema":{"type":"string","example":"BHP"}},"OptionalTicker":{"name":"ticker","in":"query","description":"ASX ticker, case-insensitive.","schema":{"type":"string","example":"BHP"}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":["string","null"]},"code":{"type":["string","number","null"]}}},"CompanyListItem":{"type":"object","required":["issuer_id","instrument_id","exchange","ticker","needs_review"],"properties":{"issuer_id":{"type":"string","example":"ASX:BHP"},"instrument_id":{"type":"string","example":"ASX:BHP"},"exchange":{"type":"string","example":"ASX"},"ticker":{"type":"string","example":"BHP"},"updated_at":{"type":["string","null"],"format":"date-time"},"needs_review":{"type":"boolean"}}},"Instrument":{"type":"object","additionalProperties":true,"properties":{"instrument_id":{"type":["string","null"],"example":"ASX:BHP:BHPAA"},"issuer_id":{"type":["string","null"],"example":"ASX:BHP"},"exchange":{"type":["string","null"],"example":"ASX"},"ticker":{"type":["string","null"],"example":"BHP"},"instrument_type":{"type":"string","enum":["option","perf_right","convertible","share"]},"is_dilutive":{"type":["boolean","null"]},"quantity":{"type":"number"},"series_name":{"type":["string","null"]},"asx_code":{"type":["string","null"]},"exercise_price":{"type":["number","null"]},"expiry":{"type":["string","null"],"format":"date"},"holder_type":{"type":["string","null"]},"vesting_condition":{"type":["string","null"]}}},"CompanySnapshot":{"type":"object","additionalProperties":true,"required":["exchange","ticker","issuer_id","instrument_id"],"properties":{"exchange":{"type":"string","example":"ASX"},"ticker":{"type":"string","example":"BHP"},"issuer_id":{"type":"string","example":"ASX:BHP"},"instrument_id":{"type":"string","example":"ASX:BHP"},"updated_at":{"type":["string","null"],"format":"date-time"},"needs_review":{"type":"boolean"},"instruments":{"type":"array","items":{"$ref":"#/components/schemas/Instrument"}},"pending_instruments":{"type":"array","items":{"$ref":"#/components/schemas/Instrument"}},"metrics":{"type":"object","additionalProperties":true},"computed_metrics":{"type":["object","null"],"additionalProperties":true}}},"Document":{"type":"object","additionalProperties":true,"required":["id","ticker","doc_id","source","raw_pdf"],"properties":{"id":{"type":"string"},"exchange":{"type":["string","null"],"example":"ASX"},"ticker":{"type":"string","example":"BHP"},"issuer_id":{"type":["string","null"],"example":"ASX:BHP"},"instrument_id":{"type":["string","null"],"example":"ASX:BHP"},"doc_id":{"type":"string"},"doc_type":{"type":["string","null"]},"title":{"type":["string","null"]},"date":{"type":["string","null"],"format":"date"},"source":{"type":"string","example":"asx"},"raw_pdf":{"type":"string","pattern":"^(hf://|https://www\\.asx\\.com\\.au/)"},"markdown":{"type":["string","null"],"pattern":"^hf://"},"raw_pdf_url":{"type":["string","null"],"format":"uri"},"markdown_url":{"type":["string","null"],"format":"uri"},"extracted":{"type":["object","null"],"additionalProperties":true}}},"DocumentPage":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"next_cursor":{"type":["string","null"]}}},"Update":{"type":"object","additionalProperties":false,"required":["id","ticker","date","headline","impact","kind"],"properties":{"id":{"type":"string","example":"03114033:filing"},"ticker":{"type":"string","example":"BHP"},"doc_type":{"type":["string","null"],"example":"Appendix 2A"},"date":{"type":"string","format":"date-time"},"headline":{"type":"string"},"impact":{"type":"string"},"kind":{"type":"string","enum":["filing","dilution","cash"]}}},"LedgerPoint":{"type":"object","required":["label","option","perf_right","convertible","pending_total"],"properties":{"label":{"type":"string","example":"Q3 2026"},"option":{"type":"number"},"perf_right":{"type":"number"},"convertible":{"type":"number"},"pending_total":{"type":"number"}}},"Ledger":{"type":"object","required":["ticker","bucket","points"],"properties":{"ticker":{"type":"string"},"bucket":{"type":"string","enum":["quarter","month"]},"points":{"type":"array","items":{"$ref":"#/components/schemas/LedgerPoint"}}}},"Screener":{"type":"object","required":["exchange","rows"],"properties":{"exchange":{"type":"string","example":"ASX"},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Quote":{"type":"object","additionalProperties":false,"required":["ticker","price","cached"],"properties":{"ticker":{"type":"string"},"price":{"type":"number"},"name":{"type":["string","null"]},"change_price":{"type":["number","null"]},"change_in_percent":{"type":["number","null"]},"volume":{"type":["number","null"]},"market_cap":{"type":["number","null"]},"cached":{"type":"boolean"},"cache_age_seconds":{"type":"integer"}}}}}}