Documentation

Overview

Use Headless Records when an agent or research workflow needs reported insider activity from public SEC filing data without scraping EDGAR or hiding data-quality assumptions. Responses preserve freshness status, deterministic caveats, methodology, request IDs, and source provenance.

The current API is for design partners with a bounded watched ticker universe. It is not full-market coverage, a dashboard product, investment advice, or self-serve production onboarding.

Authentication

The API is hosted at https://api.headlessrecords.dev. All /v1 data endpoints require an X-API-Key header and return 401 without one. The exception is GET /v1/ticker/{ticker}/preview, which is keyless and rate-limited by IP. GET /ready and GET /openapi.json are open. Public examples use hr_live_REPLACE_ME; never publish real API keys.

Endpoints

GET /v1/freshness
GET /v1/insider-activity/{ticker}/assessment
GET /v1/provenance/filing/{accession_number}
GET /v1/ticker/{ticker}/insider-selling-summary
GET /v1/ticker/{ticker}/insider-transactions
GET /v1/watchlist/freshness

GET /v1/ticker/{ticker}/preview

GET /.well-known/paid-api.json
GET /health
GET /openapi.json
GET /ready

This list is generated from the canonical OpenAPI contract at https://api.headlessrecords.dev/openapi.json. GET /.well-known/paid-api.json is a machine-readable discovery document for future L402 paid API metadata, not a data endpoint; payment enforcement is not currently active.

Freshness

GET /v1/freshness reports ingestion status for enabled watched tickers only. It separates generated_at from data_as_of and exposes per-ticker status such as fresh, stale, degraded, failed, sync_running, and never_synced.

Insider activity assessment

GET /v1/insider-activity/{ticker}/assessment returns a deterministic, non-advisory assessment over reported public SEC Form 4 activity for 30d, 90d, or 180d. It includes freshness, summary counts, structured caveats, methodology, and source references.

Filing provenance

GET /v1/provenance/filing/{accession_number} answers which source document a normalized filing came from. It includes source URLs, retrieval timestamps, content size, content type, parser/normalizer versions, and SHA-256 hashes over bytes processed by Headless Records.

Errors and rate limits

Error responses include a stable code, message, and request ID. The API documents 401 for missing or invalid keys, 404 where a resource is not available, 429 with Retry-After when rate limited, and 500 with request_id for support.

MCP server

A local stdio MCP server gives agents direct access to the API as tools — open source at github.com/jgmcalpine/headless-records-mcp. It is a thin client for this hosted API: it validates tool input, calls api.headlessrecords.dev with your API key, and returns responses with all caveats, provenance, and request IDs preserved. It exposes three tools: get_freshness, assess_insider_activity, and get_filing_provenance.

Known limitations

Coverage is bounded to configured watched tickers and imported filings. Form 4/A amendments, scheduled-plan context, partner-specific watchlists, active payment enforcement, and hosted remote MCP are not part of the current public surface.