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

Protected endpoints are hosted at https://api.headlessrecords.dev and require X-API-Key. 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 /ready
GET /openapi.json

The OpenAPI artifact is published at /api/openapi/headlessrecords.v1.json and maps to https://headlessrecords.dev/api/openapi/headlessrecords.v1.json on the public site.

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 integration

The API repo includes a local stdio MCP server under /mcp. It calls the hosted API with HEADLESS_RECORDS_API_KEY and exposes only 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.