io.github.EvidInvest/aether-developer

Publish (or update) a document into the marketplace. The content is chunked + embedded + indexed by a background worker; status moves from `pending` to `indexed` once that completes. Re-publishing the same external_doc_id replaces the prior version. Account must be status='active' for the worker to index; pending_review accounts queue indefinitely.

What a fund owns: an institutional manager's reported equity book from SEC Form 13F — top positions by value, with quarter-over-quarter share changes and new/increased/decreased flags. Answers 'what does Bridgewater hold', 'what did this fund buy last quarter', 'show me their largest positions'. Look up by manager name (partial match; the largest matching filer wins, since names like 'Vanguard' map to several distinct CIKs) or by exact CIK. Also returns the filer's published contact details — signatory, title, phone, and business address from the filing's cover page and signature block, each citable to the accession number. EDGAR publishes no email address for 13F filers, so none is returned and none should be inferred. Coverage: quarter ends from 2024-12-31 through 2026-06-30; the newest quarter is still filling in as filers submit, and a manager who has not filed it yet falls back to their most recent quarter, named in coverage_caveat. 13F covers US-listed long equity and options only — no shorts, cash, bonds or non-US listings — and is filed 45 days after quarter end, so it is a lagged snapshot, not a live portfolio.

Who owns a stock: institutional holders of a security from SEC Form 13F, ranked by position value, with quarter-over-quarter share changes. Answers 'who are the largest holders of NVDA', 'which funds added or trimmed this quarter', 'did anyone initiate a new position'. Give a ticker (resolved via CUSIP) or a CUSIP directly. Each holder row carries its accession number and an EDGAR source_url so the figure is verifiable against the primary filing. Coverage: quarter ends from 2024-12-31 through 2026-06-30, all ~10,000 filing managers, not just large ones; the newest quarter is still filling in as filers submit, so its holder_count is lower than a settled quarter's. Positions are aggregated per filer CIK — a single 13F contains one line per sub-manager (BlackRock's carries 42 separate NVDA lines), so per-line reading understates holders badly. One book per filer: the original 13F-HR, or the 13F-HR/A RESTATEMENT that replaced it (add-on amendments are excluded); values are USD even where the filer reported in thousands. Note total_value_usd is the sum across filers and may double-count where combination reports include other managers' holdings; coverage_caveat flags this when relevant. 13F covers US-listed long equity and options only — it does not show shorts, cash, bonds, or non-US listings, and is filed 45 days after quarter end.

Register a proxy endpoint (Mode B). Aether stores your auth secret encrypted at rest (AES-256-GCM) and routes agent queries server-to-server — agents never see your URL or token. Charge per call via the `price_per_call_usd_cents` field. Account must be status='active' for traffic to be routed.

Create a new marketplace seller account. Returns an API key (shown once). New accounts default to status='pending_review' — they can publish documents and register endpoints, but content is not surfaced in search until ops approves the account. Use the `invite_code` arg if the operator gave you one to bypass review.

Search SEC filings (10-K, 10-Q, 8-K, registration statements/prospectuses and press exhibits; S&P 500 coverage, ~10 years) with hybrid semantic + keyword retrieval. TWO MODES. Search mode (pass `query`): results ranked by relevance, highest first. FETCH MODE (omit `query`): no ranking at all — pass an issuer plus any of form_type / fiscal_year / accession_number / section and get that filing's sections back in filing-date-desc then document order, in tens of milliseconds. Use fetch when you already know WHICH document you want and only need its text. ALWAYS pass `issuer` (ticker, cik or company_name) — the company the question is about — plus `fiscal_year` and/or `form_type` when you know them. Scoped calls are fast and precise. A call with no issuer runs as scope=cross_company: slower, ranked by relevance only, and the response sets `quality_caveat` — check for that field. Use scope=cross_company deliberately only for questions that are genuinely about many companies ("which filers name NVIDIA as a supplier"). Built for agents: every hit is a ready-to-cite payload — exact filing-section text, form type, filing date, accession-numbered citation, source URL and a 0-1 confidence score — no HTML parsing, no EDGAR pagination. Use for revenue/segment figures, risk factors, M&A and contract terms, customer/supplier concentration, and any claim that must trace to a primary source. Fetch mode pages: pass the response's `next_offset` as `offset` to read past `limit`. Returned windows overlap; counts of a term over returned text are not document counts. `partial: true` means retrieval degraded; an empty result is then not proof of absence. Coverage is NOT US-only: Sweden/Bolagsverket, Japan/EDINET, Korea/DART annual reports are included. Those issuers have no US ticker — pass `issuer.company_name` (e.g. "Sivers Semiconductors", "Samsung Electronics", "Ajinomoto") or scope a whole market with `jurisdiction` (["SE"], ["JP"], ["KR"]).

List active marketplace partners (sellers) and what each offers. Each partner has zero or more 'modes': `indexed` (free queries via partner_search against published documents) and/or `proxy` (queries routed server-to-server to the seller's own API via partner_proxy_search, consuming prepaid Aether credits per call). Use the returned per-call credit costs to budget calls before invoking partner_proxy_search.

Route the agent's query server-to-server to one or more seller-registered API endpoints. Each call consumes prepaid Aether credits from the connected account at the per-call rate listed in list_partners (consumed regardless of result count). Aether holds seller credentials — agent never sees URL or token. Pass `issuer` when the question is about one company, so routing narrows to the endpoints that declare coverage of it rather than guessing the ticker from the query text — a wrong guess here spends credits on the wrong endpoint. Use list_partners first to discover available endpoints and per-call credit costs.

Search marketplace partner documents (research notes, supply-chain analyses, etc. published by registered sellers). Returns ranked chunks with explicit per-document attribution and license terms. Pass `issuer` when the question is about one company — partner documents declare ticker coverage, so a named issuer narrows to the documents that actually cover it; without one the call runs scope=cross_company over every seller's corpus and the response sets `quality_caveat`. Use list_partners first to discover available sellers + filter via the `partners` arg to scope costs.

Search the text of EU financial regulation — a 29-act corpus (~13,000 citable chunks) covering markets & securities (MiFID II, MiFIR, MAR, Prospectus, EMIR, CSDR, Short-Selling, SFTR, Benchmarks), crypto & operational resilience (MiCA, DORA), banking & prudential (CRR, CRD IV, BRRD, SRMR), funds (UCITS, AIFMD), payments & insurance (PSD2, Solvency II, IDD), sustainable finance (SFDR, Taxonomy, CSRD), the 2024 EU AML package (AMLR, AMLAR, AMLD6, Transfer-of-Funds Regulation), plus Credit Rating Agencies and GDPR. Returns ranked, citable units — Article-paragraphs, recitals, annex blocks — each with a human breadcrumb (e.g. 'MiCA 2023/1114 · Art. 4 · para. 1' or 'AMLR 2024/1624 · Art. 12 · para. 3'). Scoped to financial regulation, not all EU law. ALWAYS pass `celex` — it is this corpus's anchor, the equivalent of naming the issuer on a filing search — plus `article` when you know it. An anchored call is scope=issuer: fast and precise. With no `celex` the call runs scope=cross_company across all 29 acts, ranked by relevance only, and the response sets `quality_caveat` — check for that field. Use scope=cross_company deliberately for genuinely corpus-wide questions ("which acts impose a 72-hour incident-reporting deadline"). Narrow further with doc_type, chunk_type or AML topic; set prefer_consolidated to favour EUR-Lex consolidated text over the original OJ text.

Unified search across every Aether corpus at once — SEC filings, Japan/EDINET and Korea/DART annual reports, EU financial regulation, and earnings calls/press-release exhibits — auto-routed and merged into one corpus-tagged, citation-complete result set. Use this for MOST questions: you do NOT have to pick the right corpus, and it will not miss same-day earnings (8-K earnings exhibits live in the transcript/press corpus, which a filings-only search silently misses). Each hit carries a `corpus` tag, an accession/citation string, a source URL, a 0-1 confidence score and an anchor_id. ALWAYS pass `issuer` (ticker, cik, or company_name for non-US filers) plus `fiscal_year` when you know it — it is forwarded to every corpus, so one named subject scopes filings and earnings calls together: fast and precise. A call with no issuer runs as scope=cross_company: slower, ranked by relevance only, and the response sets `quality_caveat` — check for that field before trusting the result. Use scope=cross_company deliberately, only for questions genuinely about many issuers ("which filers name NVIDIA as a supplier"). Filters are forwarded, not dropped: form_type / accession_number / section / return_format reach the filing corpora (sec/jp/kr), quarter and fiscal_year reach the earnings-call corpus, and EU regulation takes none of them (it has no issuer, form or quarter) — a filing filter therefore narrows an omitted `corpora` to sec/jp/kr. Any field not listed here is REJECTED with a 400 naming it, rather than silently ignored. Reach for financial_search / transcript_search / regulation_search only when you deliberately want to force a single corpus. With an `issuer` and no `corpora`, EU regulation is not searched; if the issuer yields no SEC or earnings hit the response is empty with `coverage: "none"` and a `quality_caveat`, never filled from other corpora. `partial: true` means a corpus arm failed: retry before concluding absence. Returned windows overlap; counts of a term over returned text are not document counts. To page through a long document past `limit`, use financial_search / transcript_search fetch mode with `offset`. Ownership questions do not go through search at all: holdings_by_security and holdings_by_manager.

List documents this seller has published. Returns status (pending / indexed / failed / revoked) and the indexed chunk count (`indexed_chunk_count`; the legacy alias `vespa_chunk_count` carries the same value for one release).

List proxy endpoints this seller has registered. Secrets are never returned — only a `secret_configured` boolean.

Search earnings-call transcripts and earnings press-release exhibits by speaker turn (CEO/CFO prepared remarks, analyst Q&A, press releases). Returns verbatim quotes as agent-ready payloads: speaker name/role, fiscal year + quarter, call date, source_type (asr_call = our own ASR of the real call vs press_release), sec.gov source URL and citation string. Use for guidance, management tone and forward-looking color that filings don't capture; pair with financial_search to back narrative with filed numbers. ALWAYS pass `issuer` (the ticker whose calls you mean) plus `fiscal_year` when you know it — a named call is scoped to that issuer's calls, fast and precise. A call with no issuer runs as scope=cross_company: slower, ranked by relevance only, and the response sets `quality_caveat` — check for that field. Use scope=cross_company deliberately, only for questions genuinely about many companies ("which management teams talked about tariff pass-through"). Narrow further with speaker_role, lookback_quarters or source_type. FETCH MODE: omit `query` entirely and pass issuer.ticker plus fiscal_year / quarter / date_from / date_to to get that call's segments back in call-date-desc then spoken order, with no ranking and in tens of milliseconds — the right tool when you already know WHICH call you want. For onset/"first mention" questions (when did a topic first come up), bound with date_from/date_to and set order='earliest' — a date pair, not a fiscal year, is the right tool there. Fetch mode pages: pass the response's `next_offset` as `offset` to read past `limit`. Returned windows overlap; counts of a term over returned text are not document counts. `partial: true` means retrieval degraded; an empty result is then not proof of absence. A cross_company call that times out returns a clean 503 telling you to name an issuer.