Headless Records turns SEC Form 4 filings into structured API responses with freshness status, source provenance, deterministic caveats, and non-advisory activity assessments.
Built for agents and backend workflows. No scraping. No XML parsing. No guesswork about data freshness.
SEC Form 4 data is public. Using it cleanly is not.
SEC Form 4 filings contain valuable public information about reported insider transactions, but they are not designed for agents. Before an agent can safely use this data, developers must resolve tickers, fetch filings, parse XML, normalize transactions, track freshness, and preserve source references — in every workflow, for every ticker.
- Ticker resolution
- Form 4 filers are CIK-referenced, not ticker-referenced. Mapping CIKs to tickers requires an external lookup.
- XML parsing
- SEC EDGAR provides filings as XML. Each filing must be fetched, parsed, and normalized before the data is usable.
- Freshness uncertainty
- Agents cannot know whether the data they hold reflects the latest filings or a stale snapshot without explicit tracking.
- Missing provenance
- Without source references, an agent cannot verify which filing a data point came from or which source bytes were processed.
- Unstructured caveats
- Insider transactions occur for many reasons. Without deterministic caveats, agents may over-interpret raw activity counts.
An API layer over public SEC insider filings.
Headless Records provides an API layer over public SEC insider filings. It normalizes reported insider transactions, tracks freshness for watched tickers, links records to their source documents, and returns structured caveats so agents understand the limits of the data.
- Data source
- SEC EDGAR — Form 4 insider transaction filings (public record)
- Output format
- Structured JSON with typed fields, caveats, and source references
- Freshness model
- Per-ticker freshness tracking with aggregate status and staleness timestamps
- Provenance
- Each normalized filing links to its SEC source document URL, retrieval timestamp, and SHA-256 hash of the source bytes processed
- Caveats
- Deterministic, machine-readable caveat objects returned with every assessment response
- Assessment scope
- Non-advisory activity-level summaries over configurable periods (e.g., 30d, 90d). Not investment advice.
- Coverage
- Bounded watched ticker universe — not full-market coverage. Universe is configurable for design partners.
- Access model
- API key · Design partner access · Early release
Headless Records summarizes public filing activity. It does not provide investment advice, price predictions, or trading recommendations. Insider transactions can occur for many reasons, including scheduled plans, taxes, compensation, diversification, or other context not fully captured in a filing.
How agents interact with Headless Records
Three endpoints cover the core data contract. Each response is structured JSON designed for programmatic consumption. Source references and deterministic caveats are included by default.
- Base URL
https://api.headlessrecords.dev/v1- Authentication
- API key (header: X-API-Key) · Design partner access
- Format
- application/json · UTF-8
- OpenAPI spec
- Available on request to design partners
- Coverage scope
- Bounded watched ticker universe — not full-market. Universe is configurable for design partners.
Source-backed means normalized records link back to the SEC filing they were derived from. Hash-verifiable means the source document bytes processed by ingestion are hashed with SHA-256 and stored with retrieval metadata. This does not mean the SEC cryptographically signed the data.
/v1/freshnessFreshness status for the watched ticker universe
Returns freshness status for all tickers in the configured watched universe. Use this before any assessment call to verify data currency. Freshness applies only to the watched ticker universe — not full-market coverage.
Response fields
- aggregate_status
- fresh | stale | degraded | failed
- generated_at
- ISO-8601 timestamp — when this response was generated
- data_as_of
- ISO-8601 timestamp — effective data cutoff
- tickers
- Per-ticker freshness array: ticker, status, last_synced_at, staleness_seconds
- coverage_note
- Freshness applies only to the watched ticker universe, not full-market coverage
Example response
GET /v1/freshness
{
"aggregate_status": "fresh",
"generated_at": "2024-11-14T09:31:02Z",
"data_as_of": "2024-11-14T09:00:00Z",
"tickers": [
{
"ticker": "AAPL",
"status": "fresh",
"last_synced_at": "2024-11-14T08:55:10Z",
"staleness_seconds": 215
},
{
"ticker": "MSFT",
"status": "fresh",
"last_synced_at": "2024-11-14T08:57:43Z",
"staleness_seconds": 197
}
],
"coverage_note": "Freshness applies to the watched ticker universe only."
}fresh / stale / degraded / failed / never_synced — status set deterministically based on last sync timestamp.
/v1/provenance/filing/{accession_number}Source provenance for a specific filing
Returns provenance metadata for a filing linked to a stored source document. Provenance answers: which source document did this normalized filing come from, and what exact source bytes did the system process? Use accession_number values from assessment source references.
Response fields
- accession_number
- SEC accession number — unique filing identifier (e.g., 0001234567-24-001234)
- sec_source_url
- Direct URL to the SEC EDGAR source document used in ingestion
- source_metadata_url
- URL to SEC EDGAR filing index for the accession number
- retrieved_at
- ISO-8601 timestamp when the source document was fetched
- content_sha256
- SHA-256 hash of the source document bytes processed — for verification of which payload the system used
- content_size_bytes
- Byte size of the source document at retrieval time
- content_type
- MIME type of the source document (typically application/xml)
- parser_version
- Version of the parser applied
- normalizer_version
- Version of the normalizer applied
Example response
GET /v1/provenance/filing/0001234567-24-001234
{
"accession_number": "0001234567-24-001234",
"sec_source_url": "https://www.sec.gov/Archives/edgar/data/...",
"retrieved_at": "2024-11-14T08:55:08Z",
"content_sha256": "a3f9c2d1e8b4057f...",
"content_size_bytes": 14872,
"content_type": "application/xml",
"parser_version": "form4-parser@1.4.0",
"normalizer_version": "normalizer@2.1.0"
}content_sha256 is a SHA-256 hash of the SEC document bytes processed. It allows verification of which source payload the system used — not a blockchain or tamper-proof record.
/v1/insider-activity/{ticker}/assessmentNon-advisory insider activity assessment
Returns a deterministic, non-advisory assessment of reported insider filing activity for a ticker over a selected period. The assessment describes reported filing activity only — it does not assess whether a stock is good or bad, and is not investment advice.
Response fields
- ticker
- The requested ticker symbol
- period
- Assessment period parameter (e.g., 90d, 30d)
- activity_level
- none | low | moderate | elevated — volume of reported activity
- dominant_activity
- none | purchases | sales | mixed | other — character of reported transactions
- data_quality
- clean | limited | degraded | unavailable — quality signal for agent confidence
- summary_text
- Human-readable one-line summary of reported activity for the period
- caveats
- Array of structured caveat objects: { code, severity, message }. Always present.
- sources
- Array of source reference objects: { accession_number, provenance_status, content_sha256 }
- methodology
- Methodology descriptor explaining how the assessment was computed
Example response
GET /v1/insider-activity/AAPL/assessment?period=90d
{
"ticker": "AAPL",
"period": "90d",
"assessment": {
"activity_level": "moderate",
"dominant_activity": "sales",
"data_quality": "clean",
"summary_text": "Reported insider activity was moderate during the selected period."
},
"caveats": [
{
"code": "period_limited",
"severity": "info",
"message": "This assessment covers only the selected period."
},
{
"code": "not_financial_advice",
"severity": "info",
"message": "This response summarizes public filing data and is not financial advice."
}
],
"sources": [
{
"accession_number": "0001234567-24-001234",
"provenance_status": "available",
"content_sha256": "a3f9c2d1e8b4057f..."
}
]
}Not financial advice. activity_level and dominant_activity describe reported filing patterns only. Query params: period (90d, 30d, etc.), freshness_window_hours.
Who this is for
Headless Records is built for developers building on public SEC data — not for retail investors looking for trading signals.
- Finance agent builder
- Need: Needs fresh, normalized insider transaction data without maintaining a scraper or XML parser.
Fit: Headless Records provides a single REST call that returns structured JSON with freshness status and source references. - AI workflow developer
- Need: Needs machine-readable caveats so the agent can reason about data quality and limitations without hallucinating.
Fit: Every assessment includes deterministic caveat objects that agents can parse and act on. - Research tool builder
- Need: Needs source references to allow users to verify claims back to primary SEC filings.
Fit: Provenance endpoint links every normalized filing to its SEC EDGAR source document and SHA-256 hash. - Fintech data infrastructure team
- Need: Needs a reliable freshness signal to schedule downstream processing without polling EDGAR directly.
Fit: GET /v1/freshness returns aggregate and per-ticker freshness status with data_as_of timestamps. - Design partner / early evaluator
- Need: Wants to shape the API surface, freshness model, and watched ticker universe for their specific use case.
Fit: Design partners can help define the universe, request endpoints, and influence the methodology before general availability.
Building a finance agent or research workflow?
We are looking for developers building finance agents, research workflows, and public-record data tools. Design partners can help shape the API surface, freshness model, watched ticker universe, and example workflows.
Request design partner accessOr email directly: hello@headlessrecords.dev
Who we are looking for
- Finance agent builders
- Teams building agents that consume, reason over, or report on SEC insider filing data.
- Research workflow builders
- Developers building tools that surface public-record data for analysts or researchers.
- Backend data pipeline teams
- Engineering teams that need normalized, freshness-tracked insider data as a reliable upstream source.
- AI infrastructure builders
- Teams evaluating agent-native API patterns, including MCP-compatible data sources.
What to include in your request
- Name and company / project
- What you are building
- Which tickers or universe matter to you
- How fresh the data needs to be
- Preferred access style (API key · MCP · pay-per-call)