{ "openapi": "3.0.3", "info": { "title": "PIT API", "version": "0.1.0", "contact": { "name": "AQX LLC", "email": "operations@aqx.llc", "url": "https://pit.aqx.llc" }, "license": { "name": "Proprietary. Self-serve is internal use only. Commercial redistribution requires a license.", "url": "https://pit.aqx.llc/license" }, "description": "PIT sells the information set at time T. Massive gives you the tape; this\nAPI gives you what was knowable then.\n\nPython sugar: `query_as_of(..., known_at=...)` maps to `GET /v1/news`.\n\n## Field stability\n\n`/v1` is additive. Envelope field names, error codes, header names, and\nquery parameter names are stable and are never reused for a new meaning.\nNew fields may appear without a version bump. Nullable clocks stay\nnullable; `available_at` is never imputed. Deprecation, when needed, uses\nthe `Deprecation` header.\n\nEvery timestamp, in and out, is RFC3339 UTC with a literal `Z`\n(`2023-03-10T23:59:59Z`). A numeric offset is rejected on input rather\nthan converted, so clock parameters are declared as pattern-constrained\nstrings rather than `format: date-time`: that format permits offsets we\ndo not accept, and a spec promising a format the server rejects generates\nan SDK that cannot make a single request.\n\nEnvelope on every JSON response:\n\n```json\n{\n \"request_id\": \"uuid\",\n \"corpus_version\": \"sha256:…\",\n \"as_of\": \"2023-03-10T23:59:59Z\",\n \"visible_by\": \"published_at\",\n \"status\": \"ok\",\n \"results\": [],\n \"next_cursor\": null,\n \"count\": 0,\n \"coverage\": { \"touched\": [], \"missing\": [] },\n \"error\": null\n}\n```\n\nEmpty complete cut: HTTP 200, `status=ok`, `count=0`, `results=[]`,\n`error=null`. Coverage hole: HTTP 409, `status=coverage_missing`,\n`count` is JSON null, `error.code=coverage_missing`. Those two responses\nare not interchangeable. Missing coverage is not zero events.\n\nA hole is on one of two axes, told apart by the shape of the key in\n`coverage.missing`: a partition (`sec.edgar/2023-03-10`) we have not\ningested, or an identity cut (`identity.ticker/FB@2023-03-10`) whose\nticker no point-in-time interval places at `as_of`.\n\nCursor pagination: `limit` default 100, max 1000. Stable sort\n`(published_at, id)`. A `limit` outside 1..1000 is `400 invalid_request`,\nnot a silent clamp, and `/v1/coverage` and `/v1/files` page on the same\ncontract.\n\n`next_cursor` is opaque and bound. It carries the operation, the filter\nset and the `corpus_version` that answered, and it is validated on the\nway back in: a cursor replayed against a different cut, a different list\nor a different corpus is refused rather than resumed. That is a product\nproperty, not a guard rail — a page walk over a point-in-time corpus only\nmeans anything if every page came from one corpus_version. See the\n`cursor` parameter for the two refusals.\n\n`count` is JSON null whenever we did not answer — a coverage hole, and\nevery error including `429`. `count: 0` means we answered and the answer\nis none. Those are the two states this product is sold on; do not read a\nrefusal as an empty result.\n\nParameters are checked, not guessed at. A query parameter an operation\ndoes not declare is `400 invalid_request` naming it, as is the same\nparameter sent twice, an unknown `source`, and `ticker` together with\n`cik`. A filter the server drops is a wrong answer with a 200 on it.\n\nHTTP semantics: a path that exists under another method is `405` with\n`Allow`; a trailing slash on a `/v1` route is `301` to the slashless\nform; `OPTIONS` reports that route's own methods. A historical cut is\nimmutable given `corpus_version`, so `200`s carry `ETag` and\n`Cache-Control` and honour `If-None-Match` with `304`.\n\nAuth: `Authorization: Bearer pit_live_…`. Public samples watermark\n`sample: true` and use this same envelope.\n\nFlat files return a signed GCS URL, never a packed custom binary.\n" }, "servers": [ { "url": "https://api.pit.aqx.llc", "description": "Production" }, { "url": "https://api.staging.pit.aqx.llc", "description": "Staging" }, { "url": "http://127.0.0.1:8080", "description": "Local" } ], "tags": [ { "name": "public", "description": "No account. Sample playground and discovery." }, { "name": "news", "description": "As-of news and became_knowable." }, { "name": "coverage", "description": "Coverage certificates. Holes are labeled." }, { "name": "mapping", "description": "Ticker ↔ CIK valid at T. Not the current universe." }, { "name": "files", "description": "Power-plan GCS partitions." }, { "name": "stream", "description": "SSE of new records with available_at." }, { "name": "account", "description": "Session, keys, billing." } ], "paths": { "/health": { "get": { "tags": [ "public" ], "operationId": "getHealth", "summary": "Liveness", "description": "The documented envelope, like every other JSON route. `results[0]`\ncarries `ok` and the `corpus_version` this process loaded.\n", "security": [], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/llms.txt": { "get": { "tags": [ "public" ], "operationId": "getLlmsTxt", "summary": "Agent index (API, clocks, license)", "security": [], "responses": { "200": { "description": "Markdown index per llmstxt.org.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/docs": { "get": { "tags": [ "public" ], "operationId": "getDocs", "summary": "Human API docs (Scalar/Swagger)", "security": [], "responses": { "200": { "description": "HTML.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/openapi.json": { "get": { "tags": [ "public" ], "operationId": "getOpenAPI", "summary": "This specification as JSON", "description": "The same document as `/v1/openapi.yaml`, converted once at startup.\n`openapi/openapi.yaml` in the repository is the source of truth; this\nis a representation of it.\n", "security": [], "responses": { "200": { "description": "OpenAPI 3 document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "$ref": "#/components/responses/NotModified" } } } }, "/v1/openapi.yaml": { "get": { "tags": [ "public" ], "operationId": "getOpenAPIYAML", "summary": "This specification as YAML", "security": [], "responses": { "200": { "description": "OpenAPI 3 document.", "content": { "application/yaml": { "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" } } } }, "/v1/audit-log": { "get": { "tags": [ "account" ], "operationId": "listAuditLog", "summary": "Decision audit receipts for the calling key", "description": "Opt-in per request with `X-PIT-Audit: on` (Desk plan). Each receipt\nrecords route, params digest, corpus version, and the sha256 of the\nexact envelope served — never the payload itself. Cursor-paged;\n`day` filters one UTC day; `format=jsonl` streams an export.\n", "security": [ { "bearer": [] } ], "parameters": [ { "name": "day", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "jsonl" ] } } ], "responses": { "200": { "description": "Receipts page in the standard envelope" }, "403": { "description": "Plan without audit logs, in the standard error envelope" } } } }, "/v1/audit-log/stats": { "get": { "tags": [ "account" ], "operationId": "auditLogStats", "summary": "Audit writer tally, including losses", "description": "The full counter set for the calling key's audit stream. `dropped`\nand `failed` are first-class: loss is reported, never silent.\n", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Tally in the standard envelope" } } } }, "/v1/connectors/{vendor}/bars": { "post": { "tags": [ "account" ], "operationId": "connectorBars", "summary": "Daily bars via your own market-data key, pinned to the clock", "description": "Bring-your-own-key: the vendor credential arrives in `X-Vendor-Key`,\nis used for the one upstream call, and is never stored or echoed.\nDesk plan. The response's `origin` block names the vendor, fetch\ntime, and license class in force; `cached` is false unless a\nverified vendor grant permits otherwise.\n", "security": [ { "bearer": [] } ], "parameters": [ { "name": "vendor", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "massive", "tiingo" ] } }, { "name": "X-Vendor-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized daily bars in the standard envelope" }, "403": { "description": "Plan or vendor refusal, in the standard error envelope" } } } }, "/v1/meta": { "get": { "tags": [ "public" ], "operationId": "getMeta", "summary": "Corpus version, clocks, plans, corpus shape", "description": "Everything needed to form a valid query without guessing: the clock\nvocabulary, the lanes, the plans, and the corpus shape — which\nsources this deployment holds and the certified span of each. `source`\nmust be one of `sources`; anything else is `400`, never a certified\nempty.\n", "security": [], "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "200": { "description": "Envelope; results is a one-element Meta list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } } } } } }, "/v1/sample/news": { "get": { "tags": [ "public" ], "operationId": "getSampleNews", "summary": "Public as-of sample", "description": "Watermark `sample: true`. Not a free API key.", "security": [], "parameters": [ { "$ref": "#/components/parameters/Example" }, { "$ref": "#/components/parameters/AsOfOptional" }, { "$ref": "#/components/parameters/VisibleBy" } ], "responses": { "200": { "$ref": "#/components/responses/NewsOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sample/diff": { "get": { "tags": [ "public" ], "operationId": "getSampleDiff", "summary": "Sample became_knowable", "security": [], "parameters": [ { "$ref": "#/components/parameters/Example" }, { "$ref": "#/components/parameters/AsOfStart" }, { "$ref": "#/components/parameters/AsOfEnd" }, { "$ref": "#/components/parameters/VisibleBy" } ], "responses": { "200": { "$ref": "#/components/responses/NewsOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sample/coverage": { "get": { "tags": [ "public" ], "operationId": "getSampleCoverage", "summary": "Sample coverage certificates", "security": [], "parameters": [ { "$ref": "#/components/parameters/Example" }, { "$ref": "#/components/parameters/AsOfOptional" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/PartitionDate" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/CoverageOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "409": { "$ref": "#/components/responses/CursorExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/sample/mapping": { "get": { "tags": [ "public" ], "operationId": "getSampleMapping", "summary": "Sample identity-as-of", "security": [], "parameters": [ { "$ref": "#/components/parameters/Example" }, { "$ref": "#/components/parameters/AsOfOptional" } ], "responses": { "200": { "$ref": "#/components/responses/MappingOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "409": { "$ref": "#/components/responses/CoverageMissing" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/news": { "get": { "tags": [ "news" ], "operationId": "listNews", "summary": "query_as_of", "description": "Records visible by `as_of` on `visible_by`. `as_of` is required.\nPass `ticker` **or** `cik`, never both: `ticker` is resolved to CIKs\nthrough identity-as-of, so the two together are an intersection, and\nsending both is `400 invalid_request`. Fail closed if the named clock\nis null.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/Cik" }, { "$ref": "#/components/parameters/AsOf" }, { "$ref": "#/components/parameters/VisibleBy" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/NewsOK" }, "400": { "$ref": "#/components/responses/InvalidClock" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/news/diff": { "get": { "tags": [ "news" ], "operationId": "diffNews", "summary": "became_knowable(T0, T1)", "description": "Rows that became visible between `as_of_start` and `as_of_end` on the\nsame clock. Not \"rows whose `event_at` sits in the window\". Pass\n`ticker` or `cik`, never both.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/Cik" }, { "$ref": "#/components/parameters/AsOfStart" }, { "$ref": "#/components/parameters/AsOfEnd" }, { "$ref": "#/components/parameters/VisibleBy" }, { "$ref": "#/components/parameters/Lane" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/NewsOK" }, "400": { "$ref": "#/components/responses/InvalidClock" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/news/{id}": { "get": { "tags": [ "news" ], "operationId": "getNews", "summary": "One record by id, at a cut", "description": "`as_of` is required here for the same reason it is required on\n`/v1/news`: a fetch with no clock is outside the plan window and\noutside the point-in-time contract. A row that exists but is not\nvisible at `as_of` is `404` — it is not knowable yet, which is a\ndifferent fact from \"no such row\", and the message says which.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AsOf" }, { "$ref": "#/components/parameters/VisibleBy" } ], "responses": { "200": { "$ref": "#/components/responses/NewsOK" }, "400": { "$ref": "#/components/responses/InvalidClock" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/coverage": { "get": { "tags": [ "coverage" ], "operationId": "getCoverage", "summary": "Coverage certificates", "description": "`row_count` is JSON null when the partition is missing. A missing\npartition is not an empty news list.\n\nPaged like every other list: `limit` defaults to 100 and `next_cursor`\nis the opaque token for the next page. `limit` and `cursor` used to be\naccepted and ignored here while the whole list came back in one\nresponse.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/PartitionDate" }, { "$ref": "#/components/parameters/AsOfOptional" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/CoverageOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "409": { "$ref": "#/components/responses/CursorExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mapping/ticker/{ticker}": { "get": { "tags": [ "mapping" ], "operationId": "getMappingByTicker", "summary": "Identity as-of for a ticker", "description": "The intervals that place this ticker at `as_of`. A ticker no\npoint-in-time interval places there is a coverage hole keyed\n`identity.ticker/TICKER@YYYY-MM-DD` — `409`, `count` null — the same\nanswer `/v1/news?ticker=…` gives for the same fact. It is never\nresolved from today's ticker file.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "example": "FB" } }, { "$ref": "#/components/parameters/AsOf" } ], "responses": { "200": { "$ref": "#/components/responses/MappingOK" }, "400": { "$ref": "#/components/responses/InvalidClock" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "409": { "$ref": "#/components/responses/CoverageMissing" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mapping/cik/{cik}": { "get": { "tags": [ "mapping" ], "operationId": "getMappingByCik", "summary": "Identity as-of for a CIK", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "example": "0001326801" } }, { "$ref": "#/components/parameters/AsOf" } ], "responses": { "200": { "$ref": "#/components/responses/MappingOK" }, "400": { "$ref": "#/components/responses/InvalidClock" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/files": { "get": { "tags": [ "files" ], "operationId": "listFiles", "summary": "List GCS partitions", "description": "Power plan. Each file is a signed GCS URL.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/FilesOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "409": { "$ref": "#/components/responses/CursorExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/files/{id}": { "get": { "tags": [ "files" ], "operationId": "getFile", "summary": "One partition; signed GCS GET", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/FilesOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/stream": { "get": { "tags": [ "stream" ], "operationId": "streamNews", "summary": "SSE of new records", "description": "`text/event-stream`. Each `data` line is a NewsRecord JSON object\nwith `available_at` set. Same clock fields as the REST envelope.\nWebSocket is later; same payload.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/Cik" }, { "$ref": "#/components/parameters/Lane" } ], "responses": { "200": { "description": "SSE stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/PlanRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/auth/google/start": { "get": { "tags": [ "account" ], "operationId": "authGoogleStart", "summary": "Google OAuth redirect", "security": [], "responses": { "302": { "$ref": "#/components/responses/Redirect" }, "503": { "$ref": "#/components/responses/AuthNotConfigured" } } } }, "/v1/auth/google/callback": { "get": { "tags": [ "account" ], "operationId": "authGoogleCallback", "security": [], "responses": { "302": { "$ref": "#/components/responses/Redirect" }, "503": { "$ref": "#/components/responses/AuthNotConfigured" } } } }, "/v1/auth/github/start": { "get": { "tags": [ "account" ], "operationId": "authGithubStart", "summary": "GitHub OAuth redirect", "security": [], "responses": { "302": { "$ref": "#/components/responses/Redirect" }, "503": { "$ref": "#/components/responses/AuthNotConfigured" } } } }, "/v1/auth/github/callback": { "get": { "tags": [ "account" ], "operationId": "authGithubCallback", "security": [], "responses": { "302": { "$ref": "#/components/responses/Redirect" }, "503": { "$ref": "#/components/responses/AuthNotConfigured" } } } }, "/v1/auth/email/start": { "post": { "tags": [ "account" ], "operationId": "authEmailStart", "summary": "Magic link", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "503": { "$ref": "#/components/responses/AuthNotConfigured" } } } }, "/v1/auth/email/callback": { "get": { "tags": [ "account" ], "operationId": "authEmailCallback", "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "$ref": "#/components/responses/Redirect" } } } }, "/v1/auth/logout": { "post": { "tags": [ "account" ], "operationId": "authLogout", "security": [ { "CookieAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" } } } }, "/v1/me": { "get": { "tags": [ "account" ], "operationId": "getMe", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/keys": { "get": { "tags": [ "account" ], "operationId": "listKeys", "summary": "List key prefixes", "description": "Raw secret is never returned on list.", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "account" ], "operationId": "createKey", "summary": "Create key; secret shown once", "security": [ { "CookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "expires_at": { "type": "string", "nullable": true, "description": "RFC3339 UTC with a literal `Z`, in the future. A\nconstrained string for the same reason as `as_of`.\n", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$", "example": "2027-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequired" } } } }, "/v1/keys/{id}": { "delete": { "tags": [ "account" ], "operationId": "revokeKey", "security": [ { "CookieAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/billing/checkout": { "post": { "tags": [ "account" ], "operationId": "billingCheckout", "summary": "Stripe Checkout", "description": "Required attestation. If Stripe env is missing, HTTP 503\n`billing_not_configured`.\n", "security": [ { "CookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan_id", "attestation" ], "properties": { "plan_id": { "type": "string", "enum": [ "researcher", "power", "desk" ] }, "attestation": { "type": "boolean", "description": "Must be true. Internal use only." } } } } } }, "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/CommercialLicenseRequired" }, "503": { "$ref": "#/components/responses/BillingNotConfigured" } } } }, "/v1/billing/portal": { "post": { "tags": [ "account" ], "operationId": "billingPortal", "security": [ { "CookieAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/BillingNotConfigured" } } } }, "/v1/billing/usage": { "get": { "tags": [ "account" ], "operationId": "billingUsage", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/billing/webhook": { "post": { "tags": [ "account" ], "operationId": "billingWebhook", "summary": "Stripe webhook", "security": [], "responses": { "200": { "$ref": "#/components/responses/EnvelopeOK" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pit_live", "description": "API key. Prefix `pit_live_`. Shown once at create. Hash at rest." }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "pit_session", "description": "HttpOnly session. Secure in staging/prod. SameSite=Lax." } }, "parameters": { "AsOf": { "name": "as_of", "in": "query", "required": true, "description": "Knowledge cut: what was knowable at this instant. RFC3339 UTC with a\nliteral `Z`. A numeric offset such as `-05:00` is rejected rather than\nconverted, and a bare date is rejected because an interval is not an\ninstant; the error says which of the two you sent.\n\nDay-resolution `published_at` is `23:59:59Z` on its own UTC date, so\nan intraday cut such as `2023-03-10T12:00:00Z` excludes that whole\nday. That is deliberate and conservative — a date with no time is an\ninterval, and the honest encoding of one you must not read early is\nits end — but it surprises: the same query at `T23:59:59Z` and at\n`T12:00:00Z` can differ by a day's filings.\n\nThe schema is a constrained string, not `format: date-time`, on\npurpose. `date-time` permits any offset, so a generated client\nserialised its own datetime — the Python SDK emitted\n`2023-03-10T23:59:59.000000+0000` — and every call it made came back\n`400 invalid_clock`. A spec must not promise a format the server\nrejects. The pattern is exactly what the server accepts, codegen\npasses the string through, and the thin wrappers\n(`query_as_of(known_at=…)`) do the formatting.\n", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$", "example": "2023-03-10T23:59:59Z" } }, "AsOfOptional": { "name": "as_of", "in": "query", "required": false, "description": "Knowledge cut, RFC3339 UTC with a literal `Z`. Omitted means the\nlatest cut this route can serve. A numeric offset is rejected, not\nconverted; see the `as_of` parameter on `/v1/news` for why the schema\nis a pattern rather than `format: date-time`.\n", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$", "example": "2023-03-10T23:59:59Z" } }, "AsOfStart": { "name": "as_of_start", "in": "query", "required": true, "description": "T0 of became_knowable, exclusive. RFC3339 UTC with a literal `Z`;\na numeric offset is rejected, not converted.\n", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$", "example": "2023-03-09T20:00:00Z" } }, "AsOfEnd": { "name": "as_of_end", "in": "query", "required": true, "description": "T1 of became_knowable, inclusive. RFC3339 UTC with a literal `Z`;\na numeric offset is rejected, not converted.\n", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$", "example": "2023-03-10T23:59:59Z" } }, "VisibleBy": { "name": "visible_by", "in": "query", "required": false, "description": "Clock used for visibility. Default `published_at`.\n`available_at` is strict PIT and will empty most SEC rows in v1.\nThat is correct. Fail closed if the named clock is null.\n", "schema": { "type": "string", "enum": [ "published_at", "available_at", "committed_at" ], "default": "published_at" } }, "Ticker": { "name": "ticker", "in": "query", "description": "Resolved to CIKs through identity-as-of at `as_of`, never through\ntoday's ticker file. Letters, digits, `.` and `-`, at most 16\ncharacters. A ticker no point-in-time interval places at `as_of` is a\ncoverage hole keyed `identity.ticker/TICKER@YYYY-MM-DD`, not zero\nevents: `ticker=FB\u0026as_of=2023-03-10` is a hole because FB became META\non 2022-06-09.\n", "schema": { "type": "string", "example": "SIVB" } }, "Cik": { "name": "cik", "in": "query", "description": "SEC CIK, with or without leading zeros. Mutually exclusive with\n`ticker`: sending both is `400 invalid_request`.\n", "schema": { "type": "string", "example": "0000719733" } }, "Lane": { "name": "lane", "in": "query", "description": "Corpus lane. Default `certified_pit`. Lanes are never mixed in one\nanswer.\n", "schema": { "type": "string", "enum": [ "certified_pit", "forward_first_seen" ], "default": "certified_pit" } }, "Source": { "name": "source", "in": "query", "description": "One source namespace. The vocabulary is closed: an id this corpus\ndoes not hold is `400 invalid_request` naming the valid set, never a\ncertified empty cut. `GET /v1/meta` lists what this deployment\nactually holds, which is the authority; the enum here is every id the\ncorpus can carry.\n", "schema": { "type": "string", "example": "sec.edgar", "enum": [ "sec.edgar", "us.federal_register.pi", "us.cftc.cot", "us.ofac.sdn", "us.fda.enforcement.drug", "us.fda.enforcement.device", "us.fda.enforcement.food", "gleif.lei" ] } }, "PartitionDate": { "name": "date", "in": "query", "description": "Partition date (UTC, `YYYY-MM-DD`). With `source`, a day we have not\ningested comes back as a missing certificate, not a 404.\n", "schema": { "type": "string", "format": "date", "example": "2023-03-10" } }, "Limit": { "name": "limit", "in": "query", "description": "Page size. Default 100, maximum 1000. A value outside that range is\n`400 invalid_request` — it is not clamped, because a clamped page\nthat reports no error reads as the whole answer.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque `next_cursor` from the previous page of **this same query**.\nAnything else is refused, never a silent first page.\n\nA cursor is bound to the walk that minted it: the operation, the\nfilter set (`as_of` or the `as_of_start`/`as_of_end` pair,\n`visible_by`, `ticker`/`cik`, `lane`, `source`) and the\n`corpus_version` that answered. Send the same query again with the\ncursor added and nothing else changed. `limit` is not bound — a walk\nmay change page size.\n\nRefusals:\n\n- `400 invalid_request`, `param: cursor` — the token is not one of\n ours, or it was minted for a different operation or a different cut.\n Cursors from `/v1/news`, `/v1/coverage` and `/v1/files` are not\n interchangeable.\n- `409 cursor_expired` — the corpus moved while the walk was open.\n The corpus reloads on a timer, so a long walk or one resumed from a\n persisted cursor can span two `corpus_version`s. Start again from\n the first page; compare `corpus_version` to see what changed.\n", "schema": { "type": "string" } }, "Example": { "name": "example", "in": "query", "schema": { "type": "string", "enum": [ "svb", "aapl", "meta" ], "default": "svb" } } }, "headers": { "X-Request-Id": { "description": "Echoed or minted UUID. Also Envelope.request_id.", "schema": { "type": "string", "format": "uuid" } }, "X-Corpus-Version": { "description": "SHA-256 of corpus MANIFEST.json. Also Envelope.corpus_version.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed in the current window (plan rate per minute).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "UTC unix seconds when the window resets (GitHub convention).", "schema": { "type": "integer", "format": "int64" } }, "Retry-After": { "description": "Delta-seconds until a 429 client may retry (RFC 9110).", "schema": { "type": "integer" } }, "Deprecation": { "description": "Unused in v1. Reserved for doomed fields later.", "schema": { "type": "string" } }, "ETag": { "description": "Strong validator: the corpus version that produced this answer plus\nthe request that asked for it. Send it back as `If-None-Match`.\n", "schema": { "type": "string" } }, "Cache-Control": { "description": "`max-age=300` on a historical cut, which is immutable given\n`corpus_version`; `max-age=0, must-revalidate` on a live one;\n`no-store` on an error. `public` on the sample routes, `private`\nelsewhere.\n", "schema": { "type": "string" } }, "Allow": { "description": "Methods this path accepts. Sent with 405 and OPTIONS.", "schema": { "type": "string" } } }, "responses": { "EnvelopeOK": { "description": "Envelope, status ok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "NewsOK": { "description": "Envelope whose results are NewsRecord. Empty complete cut has\ncount 0 and error null.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "emptyComplete": { "summary": "Certified empty (zero events, coverage complete)", "value": { "request_id": "00000000-0000-4000-8000-000000000001", "corpus_version": "sha256:demo", "as_of": "2023-03-09T20:00:00Z", "visible_by": "available_at", "status": "ok", "results": [], "next_cursor": null, "count": 0, "coverage": { "touched": [ "sec.edgar/2023-03-09" ], "missing": [] }, "error": null } } } } } }, "CoverageOK": { "description": "Envelope whose results are CoveragePartition.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "MappingOK": { "description": "Envelope whose results are MappingRecord.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "FilesOK": { "description": "Envelope whose results are FileObject (signed GCS).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "CoverageMissing": { "description": "Coverage hole. HTTP 409. count is JSON null. Not a silent empty list.\nRead `coverage.missing` to see which axis is missing: a partition key\nmeans we do not have that source-day, an identity key means we cannot\nplace that ticker at `as_of`.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "partitionHole": { "summary": "Partition hole (we do not have that source-day)", "value": { "request_id": "00000000-0000-4000-8000-000000000002", "corpus_version": "sha256:demo", "as_of": "2023-03-10T23:59:59Z", "visible_by": "published_at", "status": "coverage_missing", "results": [], "next_cursor": null, "count": null, "coverage": { "touched": [ "sec.edgar/2023-03-10" ], "missing": [ "sec.edgar/2023-03-10" ] }, "error": { "code": "coverage_missing", "message": "Coverage is missing for this cut. Missing coverage is not zero events.", "param": null } } }, "identityHole": { "summary": "Identity hole (ticker=FB, renamed to META on 2022-06-09)", "value": { "request_id": "00000000-0000-4000-8000-000000000003", "corpus_version": "sha256:demo", "as_of": "2023-03-10T23:59:59Z", "visible_by": "published_at", "status": "coverage_missing", "results": [], "next_cursor": null, "count": null, "coverage": { "touched": [ "identity.ticker/FB@2023-03-10", "sec.edgar/2023-03-10" ], "missing": [ "identity.ticker/FB@2023-03-10" ] }, "error": { "code": "coverage_missing", "message": "Coverage is missing for this cut. Missing coverage is not zero events.", "param": null } } } } } } }, "CursorExpired": { "description": "The cursor was minted against a `corpus_version` this process is no\nlonger serving. HTTP 409, `count` JSON null. The corpus reloads on a\ntimer, so a walk left open across a publish — or resumed from a\ncursor persisted before a deploy — spans two corpora. Resuming it\nwould splice them into one result set and report `status: ok`, so it\nis refused. Start the walk again from the first page.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "request_id": "00000000-0000-4000-8000-000000000004", "corpus_version": "sha256:demo", "status": "error", "results": [], "next_cursor": null, "count": null, "coverage": { "touched": [], "missing": [] }, "error": { "code": "cursor_expired", "message": "The corpus moved while this walk was open, so this cursor points into a corpus_version we are no longer serving.", "param": "cursor" } } } } }, "Conflict": { "description": "409 on a paged list carries one of two codes, told apart by\n`error.code`. `coverage_missing` is a hole in the corpus this cut\ndepends on. `cursor_expired` is a cursor minted against a\n`corpus_version` we no longer serve. Both set `count` to JSON null;\nneither is an empty result.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Corpus-Version": { "$ref": "#/components/headers/X-Corpus-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "partitionHole": { "summary": "Partition hole (we do not have that source-day)", "value": { "request_id": "00000000-0000-4000-8000-000000000002", "corpus_version": "sha256:demo", "as_of": "2023-03-10T23:59:59Z", "visible_by": "published_at", "status": "coverage_missing", "results": [], "next_cursor": null, "count": null, "coverage": { "touched": [ "sec.edgar/2023-03-10" ], "missing": [ "sec.edgar/2023-03-10" ] }, "error": { "code": "coverage_missing", "message": "Coverage is missing for this cut. Missing coverage is not zero events.", "param": null } } }, "cursorExpired": { "summary": "The corpus moved while this walk was open", "value": { "request_id": "00000000-0000-4000-8000-000000000004", "corpus_version": "sha256:demo", "as_of": "2023-03-10T23:59:59Z", "visible_by": "published_at", "status": "error", "results": [], "next_cursor": null, "count": null, "coverage": { "touched": [], "missing": [] }, "error": { "code": "cursor_expired", "message": "The corpus moved while this walk was open, so this cursor points into a corpus_version we are no longer serving.", "param": "cursor" } } } } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "results": [], "count": null, "error": { "code": "unauthorized", "message": "API key missing or invalid.", "param": null } } } } }, "PlanRequired": { "description": "Paid plan required, or plan lacks this SKU (e.g. files).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "plan_required", "message": "This call needs a paid plan.", "param": null } } } } }, "CommercialLicenseRequired": { "description": "Redistribution / end-user use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "commercial_license_required", "message": "End-user or redistribution use needs a commercial license. Contact operations@aqx.llc.", "param": null } } } } }, "InvalidClock": { "description": "as_of or visible_by invalid or named clock is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "invalid_clock", "message": "Clock is invalid or null. Query fails closed.", "param": "as_of" } } } } }, "InvalidRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "not_found", "message": "Resource not found.", "param": "id" } } } } }, "RateLimited": { "description": "Plan rate exceeded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "param": null } } } } }, "BillingNotConfigured": { "description": "Stripe env missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "error": { "code": "billing_not_configured", "message": "Billing is not configured.", "param": null } } } } }, "NotModified": { "description": "The caller's `If-None-Match` matches. No body. The answer it already\nholds is still the answer.\n", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } } }, "InternalError": { "description": "Unhandled server error. Reachable on every operation; `request_id`\nidentifies the request in our logs.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "count": null, "error": { "code": "internal", "message": "Internal error.", "param": null } } } } }, "AuthNotConfigured": { "description": "This login method has no credentials configured in this deployment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "status": "error", "count": null, "error": { "code": "auth_not_configured", "message": "This login method is not configured.", "param": null } } } } }, "MethodNotAllowed": { "description": "The path exists under another method. `Allow` lists them.", "headers": { "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "Redirect": { "description": "OAuth or post-login redirect.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } } }, "schemas": { "Envelope": { "type": "object", "description": "JSON body for every /v1 JSON response. Field names are stable.\ncount is JSON null whenever we did not answer — a coverage hole and\nevery error, 429 included; 0 means we answered and the answer is none.\n", "required": [ "request_id", "corpus_version", "as_of", "visible_by", "status", "results", "next_cursor", "count", "coverage", "error" ], "properties": { "request_id": { "type": "string", "format": "uuid", "x-stability": "stable" }, "corpus_version": { "type": "string", "description": "SHA-256 of MANIFEST.json. Empty before a corpus is loaded.", "x-stability": "stable" }, "as_of": { "type": "string", "format": "date-time", "nullable": true, "x-stability": "stable" }, "visible_by": { "type": "string", "nullable": true, "enum": [ "published_at", "available_at", "committed_at" ], "x-stability": "stable" }, "status": { "type": "string", "enum": [ "ok", "error", "coverage_missing" ], "x-stability": "stable" }, "results": { "type": "array", "items": {}, "description": "Never JSON null. Empty list is complete-and-empty, not a hole.", "x-stability": "stable" }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque token for the next page. Pass it back as `cursor` on the\nsame query. Null when there is no further page. Bound to the\noperation, the filter set and `corpus_version`; do not decode,\nstore beyond the walk, or hand to another endpoint.\n", "x-stability": "stable" }, "count": { "type": "integer", "nullable": true, "description": "Length of this page of results when we answered. JSON null when\nwe did not: a coverage hole, and every error including 429.\nNever 0 for a hole and never 0 for a refusal — `count: 0` is a\nserved cut whose answer is none. Clients must keep null and 0\napart; a client that reads null as 0 reports \"no events\" for a\nrate limit.\n", "x-stability": "stable" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "error": { "allOf": [ { "$ref": "#/components/schemas/Error" } ], "nullable": true }, "sample": { "type": "boolean", "description": "Watermark on public playground responses. Omitted when false,\nhere and on the rows inside `results`.\n" } } }, "Coverage": { "type": "object", "description": "A coverage key has two shapes. A partition key,\n`source_id/YYYY-MM-DD` (`sec.edgar/2023-03-10`), is one source on one\nUTC day. An identity key, `identity.ticker/TICKER@YYYY-MM-DD`\n(`identity.ticker/FB@2023-03-10`), is one ticker's identity on one UTC\nday. A ticker may not contain `/`, so the two never collide.\n\nBoth are day-grained and both obey the same rule: a key in `missing`\nmakes `Envelope.count` JSON null and `status` `coverage_missing`.\n\nAn identity key in `missing` means no point-in-time interval places\nthat ticker at `as_of` — we never curated it, the interval lapsed, or\nthe ticker was renamed away. It does not mean the company filed\nnothing. Identity is never resolved from today's ticker file; that is\nleakage.\n", "required": [ "touched", "missing" ], "properties": { "touched": { "type": "array", "items": { "type": "string", "example": "sec.edgar/2023-03-10" }, "description": "Coverage keys this query consulted, partition and identity alike.\nNever null. A query that names a `ticker` records its identity key\nhere whether or not the ticker resolved.\n" }, "missing": { "type": "array", "items": { "type": "string", "example": "identity.ticker/FB@2023-03-10" }, "description": "Holes, in either shape. Non-empty implies Envelope.count is null.\n" } } }, "Error": { "type": "object", "required": [ "code", "message", "param" ], "properties": { "code": { "type": "string", "description": "Stable machine code.", "enum": [ "unauthorized", "plan_required", "commercial_license_required", "coverage_missing", "invalid_clock", "rate_limited", "invalid_request", "not_found", "cursor_expired", "billing_not_configured", "auth_not_configured", "certificate_unverifiable", "certificate_registered", "internal" ] }, "message": { "type": "string", "description": "Plain English. Not marketing." }, "param": { "type": "string", "nullable": true } } }, "NewsRecord": { "type": "object", "description": "One public-record row. Clocks are not interchangeable.\nTicker is not stored on the row; join MappingRecord at as_of.\nas_of_visible is computed, not persisted.\n", "required": [ "id", "source_id", "lane", "published_at", "committed_at", "availability_basis", "content_sha256", "source_locator" ], "properties": { "id": { "type": "string" }, "source_id": { "type": "string", "example": "sec.edgar" }, "lane": { "type": "string", "enum": [ "certified_pit", "forward_first_seen" ] }, "form": { "type": "string", "example": "8-K" }, "accession": { "type": "string" }, "cik": { "type": "string" }, "title": { "type": "string" }, "event_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "description": "The publisher's own publication clock. Day-resolution sources are\nstamped `23:59:59Z` on their UTC date: a date with no time is an\ninterval, and the end of it is the only end a point-in-time\nproduct may read. That is why an intraday `as_of` drops that day.\n", "example": "2023-03-10T23:59:59Z" }, "available_at": { "type": "string", "format": "date-time", "nullable": true, "description": "First evidenced public availability. Null if unknown. Never invented." }, "acceptance_at": { "type": "string", "format": "date-time", "nullable": true, "description": "SEC ACCEPTANCE-DATETIME. Not available_at." }, "committed_at": { "type": "string", "format": "date-time", "description": "Our ingest time. A 2026 backfill is not 2020 knowledge." }, "availability_basis": { "type": "string", "enum": [ "unknown", "local_first_seen", "ofr_regular_pi", "scheduled_release" ] }, "revision_id": { "type": "string" }, "supersedes": { "type": "string", "nullable": true }, "content_sha256": { "type": "string" }, "source_locator": { "type": "string", "description": "Origin URL or gs:// object. Not S3." }, "sample": { "type": "boolean", "description": "Watermark on public playground rows. Omitted when false." }, "as_of_visible": { "type": "boolean", "description": "Computed for the request as_of / visible_by. Not stored." } } }, "CoveragePartition": { "type": "object", "required": [ "source_id", "partition_date", "status", "row_count" ], "properties": { "source_id": { "type": "string" }, "partition_date": { "type": "string", "format": "date", "example": "2023-03-10" }, "status": { "type": "string", "enum": [ "complete", "missing", "partial" ] }, "row_count": { "type": "integer", "nullable": true, "description": "JSON null when status is missing. 0 is a certified empty file." }, "sample": { "type": "boolean", "description": "Watermark on public playground certificates. Omitted when false." } } }, "MappingRecord": { "type": "object", "required": [ "ticker", "cik", "valid_from", "source", "leakage_risk" ], "properties": { "ticker": { "type": "string" }, "cik": { "type": "string" }, "name": { "type": "string" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_to": { "type": "string", "format": "date-time", "nullable": true }, "source": { "type": "string", "example": "curated" }, "leakage_risk": { "type": "string", "enum": [ "none", "current_universe" ], "description": "sec_company_tickers_current is current_universe." }, "sample": { "type": "boolean", "description": "Watermark on public playground rows. Omitted when false." } } }, "FileObject": { "type": "object", "description": "One parquet partition. Download via signed GCS, not S3.\n\n`storage` says which mode the response is in. On a local backend\nthere is no bucket and no signed URL, so `gcs_uri`, `url` and\n`expires_at` are JSON null and `id` — the partition path — is the\nlocator; the server's own filesystem path is never published.\n", "required": [ "id", "storage", "gcs_uri", "url", "expires_at", "corpus_version" ], "properties": { "id": { "type": "string", "example": "sec.edgar/2023/03/10.parquet" }, "source": { "type": "string" }, "partition": { "type": "string" }, "bytes": { "type": "integer", "format": "int64" }, "sha256": { "type": "string" }, "storage": { "type": "string", "enum": [ "gcs", "local" ], "description": "Where these bytes live in this deployment." }, "gcs_uri": { "type": "string", "nullable": true, "example": "gs://pit-aqx-corpus-prod/sec.edgar/2023/03/10.parquet" }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "Time-limited signed GCS HTTPS GET. Null on a local backend." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When `url` stops working. Null when there is no signed URL — never\na year-zero timestamp.\n" }, "corpus_version": { "type": "string" } } }, "Meta": { "type": "object", "description": "What a caller needs to form a valid query without guessing: the clock\nvocabulary, the lanes, the plans, and the corpus this deployment\nactually holds.\n", "properties": { "product": { "type": "string", "example": "PIT" }, "api_version": { "type": "string", "example": "0.1.0" }, "corpus_version": { "type": "string" }, "visible_by": { "type": "array", "items": { "type": "string", "enum": [ "published_at", "available_at", "committed_at" ] } }, "lanes": { "type": "array", "description": "Lane vocabulary. Lanes are never mixed in one answer.", "items": { "type": "string", "enum": [ "certified_pit", "forward_first_seen" ] } }, "sources": { "type": "array", "description": "Every source id this corpus holds a certificate for. The accepted\nvalues of the `source` parameter, in this deployment.\n", "items": { "type": "string", "example": "sec.edgar" } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "researcher", "power", "desk" ] }, "rate_per_minute": { "type": "integer" } } } }, "corpus": { "$ref": "#/components/schemas/CorpusShape" } } }, "CorpusShape": { "type": "object", "description": "The corpus bounds, off the same partition certificates `/v1/coverage`\nserves. The day states never sum: `missing_days` is a labeled hole\nand contributes nothing to `rows`, and `empty_days` is the subset of\n`complete_days` on which the publisher published nothing.\n", "required": [ "first_partition_date", "last_partition_date", "rows", "sources" ], "properties": { "first_partition_date": { "type": "string", "format": "date" }, "last_partition_date": { "type": "string", "format": "date" }, "rows": { "type": "integer", "format": "int64", "description": "Certified rows across complete and partial days." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/CorpusSource" } } } }, "CorpusSource": { "type": "object", "required": [ "source_id", "first_partition_date", "last_partition_date", "rows" ], "properties": { "source_id": { "type": "string", "example": "sec.edgar" }, "first_partition_date": { "type": "string", "format": "date" }, "last_partition_date": { "type": "string", "format": "date" }, "complete_days": { "type": "integer" }, "partial_days": { "type": "integer" }, "missing_days": { "type": "integer" }, "empty_days": { "type": "integer" }, "rows": { "type": "integer", "format": "int64" } } } } } }