Docs / Page

API Reference

All endpoints organized by retrieval layer — the same taxonomy used in MCP tool descriptions. Each endpoint includes credit cost, parameters, and code examples in four languages.

Layer 1

Document Discovery

Find which filings exist before any page-level operation. Use these endpoints to identify documents, then proceed to Layer 2 for page-level inspection.

GET/v1/search_documents1 credit

Search 8-K/6-K page-content filings by ticker, form_type, fiscal_quarter, or keyword. Returns document metadata from pipeline.src_documents (8,439 rows). For 10-K/10-Q metadata, use search_sec_filings.

Parameters

Name	Type	Required	Default	Description
ticker	string	No	—	Stock ticker (e.g. LLY, NVDA)
form_type	string	No	—	SEC form type (8-K, 6-K)
keyword	string	No	—	FTS across page_content
date_from	string	No	—	Start date (YYYY-MM-DD)
date_to	string	No	—	End date (YYYY-MM-DD)
page	integer	No	1	Page number (1-indexed)
page_size	integer	No	20	Results per page (max 100)

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/search_documents?ticker=LLY"

GET/v1/search_sec_filings1 credit

SEC filing metadata index for standardized forms (10-K, 10-Q, 20-F, S-1, DEF 14A). 11,285 rows. Use for form_type discovery — separate from search_documents (which covers page-content for 8-K/6-K).

Parameters

Name	Type	Required	Default	Description
ticker	string	No	—	Stock ticker
form_type	string	No	—	SEC form type
date_from	string	No	—
date_to	string	No	—
page	integer	No	1
page_size	integer	No	20

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/search_sec_filings?ticker=LLY&form_type=10-K"

GET/v1/list_sources1 credit

Discover available data sources for agentic retrieval by ticker, year, and source_type.

Parameters

Name	Type	Required	Default	Description
ticker	string	No	—
year	integer	No	—
source_type	string	No	—	sec_filing, xbrl_filing, earnings_calendar

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/list_sources?ticker=LLY&year=2024"

Layer 2

Page Map & Keyword

Scan page descriptions or keyword-filter within documents. Use AFTER Layer 1 and BEFORE Layer 3. Returns page_no + description pairs — no full page_content.

GET/v1/read_source_outline/{identifier}2 credits

Full page map — returns description + keywords for every page in a document. Accepts document_id (UUID) or accession_number. ~200 pages ≈ 5K tokens. Use to identify which pages to retrieve in Layer 3.

Parameters

Name	Type	Required	Default	Description
identifier	string	Yes	—	document_id (UUID) or accession_number
include_deep_labels	boolean	No	false	+1 credit — adds table_titles, views, drivers, metrics

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/read_source_outline/0000059478-24-000123"

GET/v1/search_keyword_in_source2 credits (+1 with deep labels)

Keyword FTS across page_content. Returns matching page_no + description pairs — no full page_content. Paginated. Add include_deep_labels=true for advanced metadata extraction.

Parameters

Name	Type	Required	Default	Description
identifier	string	Yes	—	document_id or accession_number
keyword	string	Yes	—	Search term (FTS via ts_rank)
include_deep_labels	boolean	No	false
page	integer	No	1
page_size	integer	No	20

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/search_keyword_in_source?identifier=0000059478-24-000123&keyword=revenue+guidance"

Layer 3

Deep Read

Fetch full page_content markdown with citation tracking. Use AFTER Layer 2 to select specific pages. Each page includes [[Table{idx}]] markers and a citation_id for provenance.

GET/v1/read_source_pages/{identifier}1 credit / page

Fetch full page_content markdown for specific pages. Accepts document_id or accession_number. pages parameter is comma-separated TEXT page_no values. Returns [[Table{'{idx}'}]] markers and agentii:// citation URLs.

Parameters

Name	Type	Required	Default	Description
identifier	string	Yes	—	document_id or accession_number
pages	string	Yes	—	Comma-separated page_no values (e.g. page42,page47)

curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://api.agentii.ai/v1/read_source_pages/0000059478-24-000123?pages=page42,page47"

Structured Data

XBRL financial facts, metrics, and rendered statements — for structured quantitative analysis.

Method	Path	Description	Credits
GET	/v1/search_xbrl_facts	XBRL facts by ticker, concept, period. 4.36M rows.	1
GET	/v1/list_xbrl_concepts	Distinct XBRL concepts. 4,896 us-gaap concepts.	1
GET	/v1/get_xbrl_fact/{id}	Single XBRL fact with full metadata.	1
GET	/v1/get_company_financials/{ticker}	Company financial overview — filings, highlights JSONB, metrics.	1
GET	/v1/read_rendered_statement/{id}	Single rendered statement. Pending DDL.	1

Coverage

Data availability and freshness metadata.

Method	Path	Description	Credits
GET	/v1/list_coverage	Per-source ticker coverage. 160 rows from gold.launch_ticker_registry.	1
GET	/v1/get_ticker_coverage/{ticker}	Single-ticker coverage across all sources with completion %.	1

Multi-Period Search

Parallel three-layer protocol across fiscal periods.

Method	Path	Description	Credits
POST	/v1/search_cross_period	Parallel 3-layer search across N fiscal periods (max 20). Only successful periods consume credits.	1/period

Companies & Earnings

Method	Path	Description	Credits
GET	/v1/search_companies	Company registry search. 165 tickers.	1
GET	/v1/get_company_profile/{ticker}	Enriched profile with coverage, XBRL count, earnings count.	1
GET	/v1/search_earnings_calendar	Earnings events, deduplicated by provider priority.	1
GET	/v1/get_earnings_calendar_event	Single earnings event by ticker+date.	1
GET	/v1/list_upcoming_earnings	Upcoming earnings, grouped by report_date.	1
GET	/v1/get_company_fiscal_calendar/{ticker}	Fiscal year definition. Essential for SEC date alignment.	1

Knowledge

Method	Path	Description	Credits
GET	/v1/list_domains	Knowledge domains. 9 domains populated. No access tier required.	1

search_entities, get_entity_knowledge, read_knowledge_block, and search_by_domain are P2 — 503 DATA_NOT_AVAILABLE until knowledge schema populates.

Utility

Method	Path	Description	Credits
GET	/v1/search_unified	Cross-source search. Results grouped by source_type.	3
POST	/v1/batch_search	Up to 20 parallel sub-queries. Partial failure supported.	Σ sub-queries
GET	/health	Shallow health (Vercel/Pingdom, no DB).	0
GET	/v1/health	Deep health (Neon + Redis probes + data_sources).	0