Documentation Index

Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

API conventions

​

Request correlation

• every response includes Request-Id
• callers can provide x-request-id to make local benchmarking and smoke output deterministic

​

Metering

• API responses include Omni-Meter-Class
• this is the canonical hint for billing/quota classification in logs, smoke output, and reconciliation jobs

​

Cost and token headers

• every /v1/* response includes Omni-Token-Count and Omni-Estimated-Cost so agents can budget natively without re-reading the pricing page
• Omni-Token-Count is an approximate output-token count computed with the o200k_base tokenizer (gpt-4o / o1 / modern-frontier encoding) as a portable proxy; consumer-model token usage may vary 10–30%
• Omni-Estimated-Cost is a dollar string at 4-decimal precision (e.g. $0.0042) reflecting the plan-discounted per-call rate pre-grant-offset
• grant and credit balance are communicated separately via Omni-Free-Grant-Remaining and Omni-Budget-Used — the final billed amount reflects grant offsets on top of the per-call estimate
• Omni-Token-Count-Estimated: true is emitted whenever Omni-Token-Count falls back to a ceil(bytes / 4) approximation — either because the response body exceeded 512 KB (and was not fully tokenized to protect p95 latency) or because the response is a non-JSON billable payload (filing downloads, csv/markdown/pdf exports). Absence of this header means the count is an exact tokenizer result from the JSON body
• counts flagged as estimated are advisory for budget planning only; do not use them for exact tokenizer-equivalence math
• error responses (4xx, 5xx), rate-limit 429, billing-required 402, and budget-gate 402 all emit Omni-Token-Count: 0 and Omni-Estimated-Cost: $0.0000 — agents should treat failed requests as free

​

Response formats

• every response-shape endpoint accepts ?view=default | compact | agent
  • default (implicit): human-readable shape with full provenance, freshness, materialization, and validation metadata
  • compact: trimmed subset of top-level fields — suitable for UI consumers that only need identifiers + dates
  • agent: agent-optimized shape that keeps essentials and citation pointers (e.g. filingUrl, accessionNumber, offsets) and drops provenance chains, freshness metadata, and pagination context not needed for retrieval
• ?view=agent and ?view=compact coexist as distinct shapes; agent is not a strict subset of compact — it ships the richer “essentials + citations” shape while compact ships a UI-friendly top-level skim
• token-count and cost headers naturally shrink in agent mode (agents pay less for compact responses). No client changes are required — header values reflect the final serialized body
• agent-mode responses preserve camelCase field names — agent mode is a projection of the default shape, not a rename. See the per-endpoint API reference for the exact agent-mode field set
• unknown values of ?view= fall back silently to default, so accidental typos never surface as a 4xx

​

Endpoints that support ?view=agent

• GET /v1/filings/latest — single filing essentials + filingUrl
• GET /v1/entities/resolve — entity with primary identifiers + match metadata
• GET /v1/statements — statement with rows/periods, provenance dropped
• GET /v1/facts — fact point items + lifted accessionNumber / filingUrl
• GET /v1/sections/search — section items + lifted startOffset / endOffset

• GET /v1/insiders — insider trade items with trade essentials, ownership flags dropped
• GET /v1/forms/144 — Form 144 filings with citation pointers
• GET /v1/offerings — offering records (S-1 / 424) with prospectus URL
• GET /v1/events/ma — M&A events with deal structure + counterparty
• GET /v1/events/enforcement — enforcement actions with release metadata
• GET /v1/events/voting-results — voting results events with proposals array (shaped)
• GET /v1/compensation — executive compensation breakdown
• GET /v1/owners/13f — 13F report with nested holdings[] (shaped)
• GET /v1/funds/nport/holdings — N-PORT holdings with nested holdings[] (shaped)
• GET /v1/companies/subsidiaries — subsidiary list with citation envelope (API-consistency, byte-neutral)

​

Versioning

• production clients should send omni-version and pin to a dated release
• additive fields can ship within a pinned version without requiring a client rebuild
• breaking behavior changes should land behind a new dated version and be called out in /docs/changelog
• migration guides should be updated in the same change when a compatibility seam is moved or removed

​

Error model

{
  "object": "error",
  "id": "err_...",
  "code": "ownership_lookup_failed",
  "type": "api_error",
  "message": "Human-readable explanation",
  "requestId": "req_...",
  "details": {}
}

​

Auth conventions

• machine access uses x-api-key
• MCP protected-resource metadata is available before WorkOS is fully configured
• OAuth authorization-server metadata intentionally returns an explicit 503 workos_authorization_server_unavailable until real WorkOS values are present