​

API Conventions

​

Request correlation

• every response includes Request-Id
• callers can provide x-request-id to make local logs and repeatable tests easier to compare

​

Metering

• API responses include secapi-meter-class
• this is the canonical hint for billing and quota classification in logs
• hosted MCP tools/call usage rows also persist mcp_tool_name; intelligence.query and signals.dilution.enhanced.get are the current MCP tools that count toward ai_queries

​

MCP JSON-RPC quota envelope

​

Cost and token headers

• every /v1/* response includes secapi-token-count and secapi-estimated-cost so agents can budget natively without re-reading the pricing page
• secapi-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%
• secapi-estimated-cost is a dollar string at 4-decimal precision (e.g. $0.0042) reflecting the plan-discounted per-call rate pre-grant-offset; it is emitted on every /v1/* 2xx regardless of token-count opt-in
• grant and credit balance are communicated separately via secapi-free-grant-remaining and secapi-budget-used; the final billed amount reflects grant offsets on top of the per-call estimate
• secapi-token-count-estimated: true is emitted whenever secapi-token-count falls back to a ceil(bytes / 4) approximation, either because the response body exceeded 512 KB 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 secapi-token-count: 0 and secapi-estimated-cost: $0.0000; agents should treat failed requests as free

​

Opting in to exact token counts

secapi-compute-headers: token-count

​

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 do not return a 4xx

​

Factor response modes

• compact: chart, table, SDK, and agent handoff shape with identifiers, dates, ranks, contribution rows, and compact trust metadata
• standard: default application shape with the fields most dashboards and portfolio workflows need
• verbose: expanded methodology, freshness, and materialization context for audits and debugging

​

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)

​

Citation + char-range spans

• GET /v1/sections/search
• GET /v1/search/semantic

​

Reference frame

​

Null-fallback semantics

​

?view=agent interaction

​

REST vs MCP shape conventions

• REST endpoints support ?view={default,compact,agent}. The agent view is the wire-byte-optimized projection — large prose drops out, the dilution verification block compresses to the canonical { confidence, crossValidationsPassed, sourceSpanResolved, modelVersion } summary, and the response shrinks 30–95% depending on the endpoint. Use it from SDK clients that want low-latency / low-token responses to forward to a UI or downstream agent.
• Factor REST endpoints use response_mode={compact,standard,verbose} for factor-specific payload shaping, because factor workflows need distinct chart/table, application, and audit shapes.
• MCP tools always return the full payload (verification block, full provenance chain, all citation pointers). MCP context is already an agent context; returning the evidence up front avoids a second fetch. Agents reasoning over MCP decide what to show to the user.

• GET /v1/dilution/events?view=agent → returns summarizeVerification(row.verification) (the contract from packages/contracts/src/verification.ts).
• dilution.events.list MCP tool → returns the full row including the unmodified verification block. No view argument is accepted.

​

Substring-match heuristic

​

Versioning

• production clients should send secapi-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 compatibility behavior changes

​

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 publicly available
• OAuth authorization-server metadata returns an explicit 503 authorization_server_unavailable if authorization metadata is not available