--- name: 1stauthor-filings description: The 1stAuthor filings domain. --- # 1stAuthor Filings 1,317,571 corporate filings and regulatory documents across US and China, in two layers. The vector layer holds 1,211,748 (semantic plus lexical): 393,660 EDGAR 8-K events, 153,857 6-K, 187,879 13D/13G ownership filings, 46,542 structured 10-K/20-F, 31,513 DEF 14A, 28,397 Form 425, 6,593 S-1, 89,029 SEC comment-letter documents (CORRESP and UPLOAD), 119,399 Chinese periodic reports, 142,037 Chinese interim announcements, 10,434 exchange inquiry letters and discipline decisions, 2,408 CSRC penalty decisions. Only the 104,690 10-Q quarterlies are Postgres-only (no vectors, by design; keyword plus filters). One-liners, counterparties, amounts, MD&A drivers, inquiry points and violation types are model-extracted; company name / tickers / SIC come from EDGAR submissions. Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `us:861838:0001104659-23-092550`, free sample query: `CEO resignation`. ## Three verbs, every domain ``` POST /v1/{domain}/search {query, filters?, top_k?} → hits[].id + a card each GET /v1/{domain}/read/{id}?level=brief|detail|full → read as deep as you need POST /v1/{domain}/ask {query, effort: low|medium|high} → an answer with real citations ``` `read` also takes `extra=` for another side of the same document and `format=json|md|html`. At `level=full`, `section=` reads one section and `characters=N` the first N characters. ## Start here - **Find filings** — `POST /v1/filings/search {"query": "CEO 辞职", "filters": {"market": "us", "event_types": "officer_director_change", "filed_year": {"gte": 2023}}}` - **Read one filing** — `GET /v1/filings/read/us:861838:0001104659-23-092550` - **Everything for one company** — `POST /v1/filings/search {"query": "*", "filters": {"cik": "861838"}}` - **Search 10-Q quarterlies (Postgres layer)** — `POST /v1/filings/search {"query": "going concern liquidity", "filters": {"form": "10-Q"}}` - **A company's latest quarterlies** — `POST /v1/filings/search {"query": "*", "filters": {"form": "10-Q", "cik": "320193"}, "sort": "date"}` ## Search filters | field | type | meaning | |---|---|---| | `market` | keyword · eq | Market | | `doc_family` | keyword · eq any | Document family | | `form` | keyword · eq any | Form / document type. 10-Q lives only in the Postgres layer (no vectors, by design); filtering on it routes the whole query there | | `filed_at` | datetime · range | Filing date range (day precision; Postgres layer only, so it routes the query there) | | `filed_year` | integer · eq range | Filing year, range | | `fiscal_year` | integer · eq range | Fiscal year, range | | `event_types` | keyword · eq any | 8-K event type (closed set, see facets) | | `report_kind` | keyword · eq any | Periodic report kind | Rarely needed, but valid: `items`, `sic`, `letter_kind`, `exchange`, `issue_categories`, `violation_types`, `company_name`, `cik`, `sec_code`, `tickers`, `counterparties`, `risk_categories`, `party_names`, `has_reply`, `has_ban`. Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`. ## Read | level | credits | returns | |---|---|---| | `brief` | 1 | Card: the fields needed to triage, same as in search hits | | `detail` (default) | 2 | Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields) | | `full` | 5 | Full text (not available yet: source documents are on NAS (raw_path); neither layer holds the body text, only structured highlights) | ## Ask `POST /v1/filings/ask {query, effort}` — Agentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [filings: ] citations; /stream is NDJSON with real token deltas. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`. `sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so. ## Also here - GET /v1/entities?q=<机构名> → 实体；GET /v1/entities/<id>/docs?domain=filings → 该机构在本域的文档 ## Facets `GET /v1/filings/facets?field=<field>` lists the legal values for `market`, `doc_family`, `form`, `event_types`, `report_kind`, `letter_kind`, `exchange`, `issue_categories`, `violation_types`, `sic` — free, no key. Use it instead of guessing a spelling. ## Working rules - **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read. - **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it. - **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists. - **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing. - **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one. Citation format: `[8-K 0001104659-23-092550]`. ## What this corpus will and will not tell you - Fields differ by doc_family: event (8-K) has items / event_types / counterparties / amounts; periodic has main_business / segments / key_numbers; 10-Q quarterlies have mdna_drivers / liquidity / legal_updates / new_or_changed_risks / outlook; inquiry_letter has issues / deadline / has_reply; penalty has violation_types / facts / legal_basis / parties. Filter by doc_family before reading fields. - The 104,690 10-Q quarterlies carry no vectors by design and live only in the Postgres layer: filtering on form=10-Q (or doc_family=periodic with market=us) routes the whole query there — lexical search, sort=date and day-precision filed_at ranges, but no semantic search. Every hit is tagged with its layer and the response says which layer answered. - Lexical search in the Postgres layer also matches model-written retrieval keywords (kw_en / kw_zh, folded into the full-text index), so a Chinese query such as 持续经营 finds English going-concern language and synonyms absent from the source text. The trade-off: the score includes that contribution and the response does not distinguish a source-text match from a keyword-only match. The keywords themselves are not returned (the store marks them recall-only). - Financial statements from 10-K / 20-F / 10-Q are not here — use XBRL; this corpus carries structured highlights only. - Source documents are on NAS (raw_path in level=detail); the index holds no full text. - The index holds no full text: level=full is not available yet (source documents are on NAS (raw_path); neither layer holds the body text, only structured highlights). --- Generated from https://api.1stauthor.com/v1/filings on 2026-10-14. Full reference: https://1stauthor.com/docs/filings/