# SourceKeel API

Base URL: https://api.sourcekeel.com
Authentication: `Authorization: Bearer sk_live_...`.
Create and manage API keys in the SourceKeel dashboard.

Public AMPX demo: `Authorization: Bearer sk_demo_ampx_readonly_v1`. Use it with the GTM endpoints below to retrieve AMPX examples. Use your own API key for other companies.

Use CIK for stable company identity. Tickers are aliases.

Check coverage before pulling (cheap, not counted against quota):
- `GET /v1/coverage?identifier={cik_or_ticker}` -> per-feature status: ready | not_materialized. An unresolved identifier returns 404 `company_not_found`.
- `GET /v1/coverage?identifier=...&feature=financials` for one feature. Use it to request only data marked `ready`.

Then call data endpoints and follow `links`, `objects`, and `applicable_extractions`.

Example issuer used in docs:
- Company: Amprius Technologies, Inc.
- Ticker: AMPX
- CIK: 0001899287
- Sample accession: 0001899287-26-000015
- Form: 10-K

GTM endpoint catalog:
- `GET /v1/coverage`: Cheap, uncounted latest-snapshot availability check for a company and optional feature. Availability is not evidence that an SEC event or field is absent.
- `GET /v1/companies`: Returns the company manifest, or searches companies when q/limit is supplied.
- `GET /v1/companies/lookup`: Resolve a CIK, ticker, or identifier to the canonical CIK-backed company record.
- `GET /v1/identifiers/resolve`: Resolve a ticker or CIK through the same CIK-first identity map.
- `GET /v1/companies/{cik_or_ticker}`: Compact company identity, SIC/schema selection, coverage, links, and object pointers.
- `GET /v1/companies/{cik_or_ticker}/earnings-release-metrics`: Complete paginated collection of SEC-filed earnings-release metrics extracted for the company.
- `GET /v1/companies/{cik_or_ticker}/earnings-official-metrics`: Complete paginated collection of independent official filing metrics used in earnings reconciliation, including qualified Q4 derivations.
- `GET /v1/companies/{cik_or_ticker}/earnings-comparisons`: Complete paginated release-to-official comparison collection with circular-source rejection and source-backed Q4 derivations.
- `GET /v1/companies/{cik_or_ticker}/sections`: Company-level section extraction index.
- `GET /v1/companies/{cik_or_ticker}/source-packages`: Filing source package manifests for the company.
- `GET /v1/companies/{cik_or_ticker}/facts`: Raw numeric SEC fact history. With no query parameters this returns the complete materialized object. Supplying a filter, limit, or cursor returns a bounded page while preserving every fact's filing and source provenance.
- `GET /v1/companies/{cik_or_ticker}/facts/latest`: Latest raw numeric SEC facts. With no query parameters this returns the complete materialized object; query parameters return a bounded page.
- `GET /v1/companies/{cik_or_ticker}/schema`: SIC/sector-selected company schema output with mapped, missing, consumed, and unmapped facts.
- `GET /v1/companies/{cik_or_ticker}/financials`: Full normalized financials by default. Set statement to return one coherent period-grouped statement with classified components, cash direction, reconciliation, and provenance; statement requests default to compact, while full adds diagnostics under details. Metric projections remain available with view=compact.
- `GET /v1/companies/{cik_or_ticker}/securities`: Latest cover-page securities table for the company, extracted from persisted SEC filing documents with row-level evidence.
- `GET /v1/companies/{cik_or_ticker}/security-lifecycle`: SEC-filing-backed listing, delisting, deregistration, active-state, and lifecycle event evidence.
- `GET /v1/companies/{cik_or_ticker}/capital-structure`: Current reported shares, accounting share averages, potential shares, and transparent share-count totals. Compact is the default; view=full preserves the same core fields and adds diagnostics under details. scope=historical returns the PIT observation ledger, and group_by=fiscal_quarter organizes those exact rows without changing them. Missing and disclosed-but-unquantified values remain explicit.
- `GET /v1/companies/{cik_or_ticker}/revenue-segments/latest`: Up to the latest four materialized revenue-segment periods, including reconciliation and derived-quarter input lineage where available.
- `GET /v1/companies/{cik_or_ticker}/events`: Item-classified filing event lens.
- `GET /v1/companies/{cik_or_ticker}/disclosure-extractions`: Structured disclosure extraction rows and field partitions.
- `GET /v1/companies/{cik_or_ticker}/amendment-diffs`: Source-backed formal amendments and ordinary subsequent filings that revise prior reported periods. Every record uses prior_accessions; relationship_type distinguishes legal amendments from ordinary revisions. Revised values become PIT-valid at the revising filing's acceptance time.
- `GET /v1/companies/{cik_or_ticker}/officer-changes`: 8-K Item 5.02 officer/director changes plus an as-of current roster composed from typed Item 5.02 and Form 3/4 role evidence, with confidence and source-history boundaries.
- `GET /v1/companies/{cik_or_ticker}/float`: DEI public float and shares outstanding facts.
- `GET /v1/companies/{cik_or_ticker}/subsidiaries`: Best-effort Exhibit 21 subsidiary rows.
- `GET /v1/companies/{cik_or_ticker}/insider-rollup`: Issuer-level insider transaction rollup.
- `GET /v1/companies/{cik_or_ticker}/proposed-sales`: Structured Form 144 proposed sale rows.
- `GET /v1/companies/{cik_or_ticker}/private-offerings`: Structured Form D private offering rows.
- `GET /v1/companies/{cik_or_ticker}/offerings`: Offering metadata lens over registration/prospectus-related filings.
- `GET /v1/companies/{cik_or_ticker}/public-offering-history`: Company-level public-offering chain history and structure rows.
- `GET /v1/companies/{cik_or_ticker}/proxy-filings`: Proxy and information statement filing lens.
- `GET /v1/companies/{cik_or_ticker}/proxy-governance`: Proxy governance table inventory, source excerpts, and conservative normalized rows for recognized table layouts.
- `GET /v1/filings`: Global filing search by company, form, date, accepted timestamp, and cursor.
- `GET /v1/documents`: Company document search by CIK/ticker and optional date window.
- `GET /v1/feed/filings`: Poll newly available filings since a timestamp.
- `GET /v1/filings/{accession}`: Single filing metadata and applicable extraction/source surface manifest.
- `GET /v1/filings/{accession}/timeliness`: Source-backed periodic filing deadline, filer class, calendar adjustment, extension linkage, and timeliness result.
- `GET /v1/filings/{accession}/documents`: Document index for one accession.
- `GET /v1/filings/{accession}/source-package`: Source package manifest for one accession.
- `GET /v1/filings/{accession}/cover-securities`: Cover-page securities rows extracted from one filing, including title, symbol, exchange, section, and evidence.
- `GET /v1/filings/{accession}/sections`: Section index for one filing.
- `GET /v1/filings/{accession}/sections/{item}`: Extracted section text and evidence for one filing item.
- `GET /v1/filings/{accession}/sections/{item}/schema`: Schema-applied disclosure extraction for a filing item.
- `GET /v1/filings/{accession}/extractions`: Disclosure extraction index for one accession.
- `GET /v1/filings/{accession}/facts`: All raw numeric SEC facts for one filing.
- `GET /v1/filings/{accession}/revenue-segments`: Revenue segment convenience rows for one filing.
- `GET /v1/filings/{accession}/events`: Item event lens for one filing.
- `GET /v1/filings/{accession}/proposed-sales`: Form 144 proposed sale rows for one filing.
- `GET /v1/filings/{accession}/offering`: Form D offering extraction for one filing.
- `GET /v1/filings/{accession}/offerings`: Offering lens for one filing.
- `GET /v1/filings/{accession}/public-offering-structure`: Source-backed public offering structure object for one registration/prospectus filing.
- `GET /v1/filings/{accession}/officer-changes`: Officer change lens enriched from the filing's Item 5.02 disclosure extraction.
- `GET /v1/filings/{accession}/float`: DEI public float and shares outstanding rows for one filing.
- `GET /v1/filings/{accession}/subsidiaries`: Subsidiary rows for one filing.
- `GET /v1/filings/{accession}/proxy`: Proxy filing lens for one filing.
- `GET /v1/filings/{accession}/proxy-governance`: Proxy governance table candidates and recognized normalized rows for one filing.
- `GET /objects/{object_key}`: Authenticated object download for keys returned by the API. Bulk object keys require Mirror access.

Response rules:
- Company, filing, fact, section, and document endpoints return complete responses.
- Search/feed endpoints use `limit` and `cursor`.
- Send `Accept-Encoding: gzip` for large JSON responses.
- Every response includes an `X-Request-Id` header. Include it when contacting support; failure bodies repeat it as `request_id`.
- A successful 2xx response never contains a top-level `error` or `failure_reason`. Empty search results remain successful 200 responses.
- Individual fields or rows may carry source-availability metadata without turning an otherwise valid resource or collection into a request failure.
- Source provenance uses accession, form, and filing metadata. External origin URLs are omitted; use a returned `object_url` for authenticated source bytes.
- Failures use `sourcekeel.failure.v1` with structured `failure_reason`. Branch on `error.code`.
- A 404 `object_not_found` with `failure_reason.evidence.reason=not_materialized` means the company is known but the requested coverage is not ready — check `/v1/coverage` before retrying.
- `company_not_found` (404) means the identifier is not covered; `invalid_identifier_format` (400) means a numeric id longer than a 10-digit CIK.
- 429 responses include a `Retry-After` header (seconds) for both rate limits and monthly quota.

OpenAPI: /openapi.json
Human docs: /docs