/v1 API reference

Hosts

The /v1 API is additive. New fields may appear without a version change. Existing field names, error codes, and parameter names maintain their meaning. Nullable fields remain nullable.

Envelope

All JSON response bodies use this structure, including errors.

{
  "request_id": "uuid",
  "corpus_version": "sha256:…",
  "as_of": "2023-03-10T23:59:59Z",
  "visible_by": "published_at",
  "status": "ok",
  "results": [],
  "next_cursor": null,
  "count": 0,
  "coverage": { "touched": [], "missing": [] },
  "error": null
}

Timestamps must use RFC3339 UTC format with a literal Z. Values without Z or with local offsets are rejected.

Pagination

Pagination uses cursors sorted by (published_at, id). The limit parameter defaults to 100 and accepts values from 1 to 1000. Other values return HTTP 400 with invalid_request. The count field contains the number of rows in the current page, so sum count across all pages to get the total.

A cursor encodes the route, query filters, and the corpus_version. To fetch the next page, send the same query with the cursor parameter added. You can change limit between pages, but all other query parameters must match. Reusing a cursor with different parameters or routes returns invalid_request for cursor. If the corpus reloads during pagination, the cursor returns cursor_expired and you must restart from the first page.

Headers

Sample routes

Sample routes do not require an Authorization header or an account. The example parameter accepts svb, aapl, or meta; other values return invalid_request. Responses include sample: true and are rate-limited to 30 requests per minute per IP.

GET /health and GET /v1/meta are also open. /v1/meta returns the corpus version, accepted clocks, plan limits, and row and certificate counts per source. A certificate is the record for one source on one day.

Paid routes

Send Authorization: Bearer pit_live_…. The as_of timestamp parameter is required on historical reads. Each query must specify either ticker or cik.

$ curl -s -H 'Authorization: Bearer pit_live_…' \
  "https://api.pit.aqx.llc/v1/news?ticker=SIVB&source=sec.edgar&as_of=2023-03-10T23:59:59Z"

Use source to filter by a specific source. If omitted, the query checks all seven sources. If any source lacks a certificate for that day, the request returns HTTP 409. See Coverage for details.

Unknown query parameters return invalid_request and name the parameter. Misspelled filters fail the request instead of widening the result set.

Errors

Error responses include an error object containing { code, message, param } alongside the standard envelope. Branch your code on code, which is stable. message is human-readable and may change between releases. param names the invalid parameter or is null.

Keys and limits

Log in using GitHub, Google, or email. Accounts support multiple API keys. Each key shows a name, prefix, created time, last-used time, and a revoke action. The secret is shown once upon creation and cannot be retrieved later. All plans can access the full ingested history.

Review plan details and rates on pricing. An API key covers internal research and applications run for yourself or your employer. Redistributing data or serving it directly to external end users requires a commercial license.