{ "openapi": "3.1.0", "info": { "title": "Aggre Data Bank - public data API", "version": "1.0", "description": "The read routes of `aggre-api` (`https://api.aggre.org`), derived from the router and\n[the schema reference](https://docs.aggre.org/api/schemas). Semantics, freshness rules and caveats of each family are in the\ncontract documents named in each operation; this file is the machine-readable shape.\n\n* **Auth**: every `/v1/*` route needs an API key, `Authorization: Bearer aggre_sk_...` or `X-API-Key`.\n `/healthz` and `/readyz` need none.\n* **Envelope**: `{ \"data\": ..., \"meta\": {...}, \"next_cursor\": ... }`. `next_cursor` is opaque; pass it\n back unchanged as `cursor`, it is `null` on the last page (and always `null` on routes without paging).\n* **Strict queries**: an unknown or repeated query parameter is `400 invalid_request`, never ignored.\n* **Errors**: [the error reference](https://docs.aggre.org/concepts/errors); every answer carries `x-request-id`. `429 rate_limited`\n (per source IP, retry after `Retry-After`) and `429 usage_limit_exceeded` (the key's quota is spent;\n do not retry) share a status and differ by `error.code`.\n* **Attribution**: rows that carry `credit`, `attribution` or `license` must be shown with it by whoever\n shows the row; the API does not compose it.\n* **Not in this file**: the Taiwan judgments routes (`/v1/legal/judgments/*`) are in\n [the judgments notes](https://docs.aggre.org/datasets/legal-statutes#judgments-and-retrieval); the console/control-plane service is in\n [the accounts API](https://docs.aggre.org/api/accounts).\n* `backend/services/api/tests/data_contract.rs` keeps this file and the router the same set of\n operations and checks every query parameter against the route's own parser.\n" }, "servers": [ { "url": "https://api.aggre.org" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "meta", "description": "Health, the dataset list and the calling key" }, { "name": "market", "description": "Crypto market data ([the dataset guide](https://docs.aggre.org/datasets))" }, { "name": "macro", "description": "Official macro series and the release calendar ([the dataset guide](https://docs.aggre.org/datasets), [the macro guide](https://docs.aggre.org/datasets/macro))" }, { "name": "filings", "description": "SEC EDGAR ([the filings guide](https://docs.aggre.org/datasets/filings)) and US Congress stock trades ([the filings guide](https://docs.aggre.org/datasets/filings))" }, { "name": "equities_tw", "description": "Taiwan listed and OTC equities, after-hours ([the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities))" }, { "name": "legal", "description": "Statutes, sanctions/exclusion lists and standard-form contracts ([the statutes guide](https://docs.aggre.org/datasets/legal-statutes), [the regulatory guide](https://docs.aggre.org/datasets/legal-regulatory), [the regulatory guide](https://docs.aggre.org/datasets/legal-regulatory))" }, { "name": "health", "description": "Health datasets: drugs, trials, providers, statistics ([the health guide](https://docs.aggre.org/datasets/health)). Every route answers 503 terms_unread until a person has read the publisher's terms." }, { "name": "onchain", "description": "On-chain and DeFi data ([the on-chain guide](https://docs.aggre.org/datasets/onchain)). Answers 503 terms_unread until a person has read the publisher's terms." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "aggre_sk_... key" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "parameters": { "InstrumentId": { "name": "instrument_id", "in": "query", "required": true, "description": "`{VENUE}:{PRODUCT}:{native}`, e.g. OKX:SPOT:SOL-USDC. Funding and open interest need a PERP or FUTURES id.", "schema": { "type": "string", "examples": [ "OKX:SPOT:SOL-USDC" ] } }, "FromMs": { "name": "from", "in": "query", "description": "Unix ms, inclusive (on `ts`).", "schema": { "type": "integer", "format": "int64" } }, "ToMs": { "name": "to", "in": "query", "description": "Unix ms, exclusive (on `ts`). Must be later than `from`.", "schema": { "type": "integer", "format": "int64" } }, "Limit1000": { "name": "limit", "in": "query", "description": "Rows per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "OrderDesc": { "name": "order", "in": "query", "description": "Sort direction (default newest first).", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "OrderAsc": { "name": "order", "in": "query", "description": "Sort direction (default oldest first).", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, "Cursor": { "name": "cursor", "in": "query", "description": "The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400.", "schema": { "type": "string" } }, "Venue": { "name": "venue", "in": "query", "description": "Exact venue code: uppercase letters and digits (OKX, BITGET, HYPERLIQUID ...).", "schema": { "type": "string", "pattern": "^[A-Z0-9]+$" } }, "Product": { "name": "product", "in": "query", "schema": { "type": "string", "enum": [ "SPOT", "PERP", "FUTURES" ] } }, "Cik": { "name": "cik", "in": "query", "description": "SEC CIK, one to ten digits, with or without leading zeros (returned padded).", "schema": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, "CikRequired": { "name": "cik", "in": "query", "required": true, "description": "SEC CIK, one to ten digits, with or without leading zeros (returned padded).", "schema": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, "InstrumentIdPath": { "name": "instrument_id", "in": "path", "required": true, "description": "A statute `instrument_id` such as `UK:LEG:ukpga/2020/1` or `TW:MOJ:A0000001:en`. It can contain `/` and `:`; the server accepts them literally or percent-encoded and sees the same id. A path ending `/provisions` is always the provisions route.", "schema": { "type": "string" } }, "ContractFormIdPath": { "name": "form_id", "in": "path", "required": true, "description": "The GUID of a standard form as listed by the collection route (36 characters; upper or lower case).", "schema": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "StatuteDataset": { "name": "dataset", "in": "query", "description": "One of the ten statute dataset ids.", "schema": { "type": "string", "enum": [ "legal.statutes.tw_moj", "legal.statutes.jp_egov", "legal.statutes.uk_legislation", "legal.statutes.ca_laws", "legal.statutes.eu_eurlex", "legal.statutes.us_ecfr", "legal.statutes.de_gii", "legal.statutes.au_federal", "legal.statutes.cn_flk", "legal.statutes.sg_sso" ] } }, "RegulatoryDatasetRequired": { "name": "dataset", "in": "query", "required": true, "description": "The name list.", "schema": { "type": "string", "enum": [ "legal.regulatory.ofac_sdn", "legal.regulatory.un_sanctions", "legal.regulatory.us_exclusions" ] } }, "HealthIncludeText": { "name": "include", "in": "query", "description": "`text` adds the long fields the list leaves out (smaller page cap).", "schema": { "type": "string", "enum": [ "text" ] } }, "HealthUpdatedSince": { "name": "updated_since", "in": "query", "description": "Rows changed at or after this moment (`YYYY-MM-DD` or an RFC 3339 timestamp), by our `updated_at`. With `cursor` this is a change feed.", "schema": { "type": "string" } }, "EmaProductNumberPath": { "name": "product_number", "in": "path", "required": true, "description": "EMA product number as published (opaque, 1-64 characters).", "schema": { "type": "string" } }, "FdaKeyPath": { "name": "key", "in": "path", "required": true, "description": "An openFDA record's `key` exactly as listed (1-1000 characters). A composite key keeps its `/` (`P140004/S092`, or `P140004/` for an original application); send it raw or as `%2F`. For content-hash datasets it is the 64-hex hash.", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "TrialsNctIdPath": { "name": "nct_id", "in": "path", "required": true, "description": "ClinicalTrials.gov study id as published (letters, digits, `_` and `-`, at most 32 characters), e.g. `NCT00000102`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" } }, "FdaSummaryKNumberPath": { "name": "k_number", "in": "path", "required": true, "description": "A 510(k) clearance number: letters then six digits (`K232060`, `DEN250040`); lower case is accepted.", "schema": { "type": "string", "pattern": "^[A-Za-z]+[0-9]{6}$" } }, "NppesNpiPath": { "name": "npi", "in": "path", "required": true, "description": "A National Provider Identifier: exactly 10 digits.", "schema": { "type": "string", "pattern": "^[0-9]{10}$" } } }, "headers": { "RequestId": { "description": "Quote this when asking for help.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying (rate_limited).", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "Error": { "description": "Structured error ([the error reference](https://docs.aggre.org/concepts/errors)).", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "429. `error.code` is `rate_limited` (per source IP: wait `Retry-After` and retry) or `usage_limit_exceeded` (the key's quota for the period is spent: do not retry).", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Stable machine code. A client must tolerate codes it does not know.", "enum": [ "unauthorized", "forbidden", "ip_not_allowed", "not_found", "invalid_request", "rate_limited", "usage_limit_exceeded", "store_unavailable", "internal", "conflict", "origin_not_allowed", "csrf_required", "step_up_required", "account_disabled", "email_mismatch", "provider_read_only", "validation_failed", "secrets_key_missing", "bootstrap_invalid", "bootstrap_disabled", "credentials_key_missing", "taken_down", "index_unavailable", "retrieval_unavailable", "corpus_not_migrated", "terms_unread" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "Meta": { "type": "object", "description": "Where the data came from and how fresh it is. Routes add a few keys of their own (listed); clients must ignore keys they do not know.", "properties": { "source": { "type": "string", "description": "The one source of the rows, or `aggre` when they mix." }, "status": { "type": "string", "enum": [ "ok", "stale", "empty" ], "description": "`stale`: our last read is older than the dataset's window. `empty`: nothing matched or nothing was ever read." }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Our newest successful read; `null` where nothing has been read yet (equities_tw)." }, "dataDate": { "type": [ "string", "null" ], "format": "date-time", "description": "The newest data point returned; what it means per route is in the contract." }, "message": { "type": [ "string", "null" ] }, "lastReadAt": { "type": [ "string", "null" ], "description": "filings: our newest successful read of the dataset." }, "dataset": { "type": "object", "description": "filings: title, terms_url, terms_read_on, credit, license." }, "series": { "description": "macro observations: the series row (macro_derived observations: the computed series row).", "oneOf": [ { "$ref": "https://docs.aggre.org/schemas/macro_series.json" }, { "$ref": "https://docs.aggre.org/schemas/macro_derived_series.json" } ] }, "restricted": { "type": "boolean", "description": "legal statutes: any returned instrument is restricted." }, "attribution": { "type": "array", "items": {}, "description": "legal statutes: attribution texts (strings) to show; equities_tw: `[{source_id, credit}]` for the sources of the rows returned." }, "licenses": { "type": "array", "items": { "type": "string" } }, "instrument_id": { "type": "string", "description": "statute provisions." }, "provision_count": { "type": "integer", "description": "statute provisions (of the version returned)." }, "version": { "$ref": "#/components/schemas/StatuteVersion", "description": "statute provisions: the version of the text the provisions are." } }, "additionalProperties": true }, "Dataset": { "type": "object", "required": [ "id", "title", "path", "store_kind" ], "properties": { "id": { "type": "string", "description": "{domain}.{category}.{name}" }, "title": { "type": "string" }, "path": { "type": "string", "description": "Where to read it (statute and name-list datasets share one route and select themselves with `?dataset=`)." }, "store_kind": { "type": "string", "enum": [ "clickhouse", "postgres" ] } } }, "WhoAmI": { "type": "object", "required": [ "key_id", "key_prefix", "name", "account", "rate_policy", "ip_allowlist_configured", "usage" ], "properties": { "key_id": { "type": "string", "format": "uuid" }, "key_prefix": { "type": "string", "description": "`aggre_sk_` plus the first 8 characters: the non-secret display prefix." }, "name": { "type": "string" }, "account": { "type": "string" }, "rate_policy": { "type": "string", "enum": [ "default", "exempt" ] }, "ip_allowlist_configured": { "type": "boolean" }, "usage": { "type": "object", "required": [ "period", "limit", "used" ], "properties": { "period": { "type": "string", "enum": [ "day", "month", "total" ] }, "limit": { "type": [ "integer", "null" ], "description": "null = unlimited." }, "used": { "type": "integer" } } } } }, "StatuteInstrument": { "type": "object", "description": "[the statutes guide](https://docs.aggre.org/datasets/legal-statutes) (`statutes.instrument`). The list leaves out `foreword`.", "required": [ "instrument_id", "dataset_id", "jurisdiction", "source", "native_id", "language", "kind", "title", "status", "extra", "content_hash", "record_id", "restricted", "first_seen_at", "fetched_at", "updated_at" ], "properties": { "instrument_id": { "type": "string" }, "dataset_id": { "type": "string" }, "jurisdiction": { "type": "string", "pattern": "^[A-Z]{2}$" }, "source": { "type": "string" }, "native_id": { "type": "string" }, "language": { "type": "string" }, "kind": { "type": "string", "enum": [ "act", "regulation", "order", "treaty", "other" ] }, "level": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "title_alt": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "in_force", "repealed", "abandoned", "withdrawn" ] }, "promulgated_on": { "type": [ "string", "null" ], "format": "date" }, "effective_on": { "type": [ "string", "null" ], "format": "date" }, "modified_on": { "type": [ "string", "null" ], "format": "date" }, "url": { "type": [ "string", "null" ] }, "extra": { "type": "object" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "record_id": { "type": "string", "format": "uuid" }, "license": { "type": [ "string", "null" ] }, "attribution": { "type": [ "string", "null" ] }, "restricted": { "type": "boolean" }, "first_seen_at": { "type": "string", "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "removed_on": { "type": [ "string", "null" ], "format": "date", "description": "Set when the source stopped listing it; the text is the last version seen." }, "foreword": { "type": [ "string", "null" ], "description": "Detail only." } } }, "StatuteProvision": { "type": "object", "required": [ "seq", "kind", "text", "content_hash" ], "properties": { "seq": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "article", "heading", "schedule", "note" ] }, "number": { "type": [ "string", "null" ] }, "heading": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "StatuteAttachment": { "type": "object", "required": [ "seq", "file_name", "file_url" ], "properties": { "seq": { "type": "integer" }, "file_name": { "type": "string" }, "file_url": { "type": "string" } } }, "StatuteVersion": { "type": "object", "description": "One version of a statute's text. `observed_from` / `superseded_at` are when Aggre first saw the text and when it saw its successor, not when the law took effect. History begins when migration 0016 was deployed. [the statutes guide](https://docs.aggre.org/datasets/legal-statutes).", "required": [ "version_no", "current", "content_hash", "title", "status", "observed_from", "superseded_at", "provision_count" ], "properties": { "version_no": { "type": "integer", "minimum": 1, "description": "The current text is the highest." }, "current": { "type": "boolean" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "in_force", "repealed", "abandoned", "withdrawn" ] }, "observed_from": { "type": "string", "format": "date-time" }, "superseded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null for the current text." }, "provision_count": { "type": "integer" } } }, "StatuteDetail": { "description": "An instrument with its foreword, provisions (at most 5000 per answer) and attachments.", "allOf": [ { "$ref": "#/components/schemas/StatuteInstrument" }, { "type": "object", "required": [ "provision_count", "provisions", "provisions_truncated", "attachments", "version_count", "versions" ], "properties": { "version_count": { "type": "integer", "description": "Versions Aggre holds, the current one included (at least 1)." }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteVersion" }, "description": "Oldest first; the last one is the current text." }, "provision_count": { "type": "integer", "description": "All provisions, not only those returned." }, "provisions": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteProvision" } }, "provisions_truncated": { "type": "boolean" }, "next_from_seq": { "type": [ "integer", "null" ], "description": "Where to continue with the provisions route when truncated." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteAttachment" } } } } ] }, "DatasetsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } } } }, "WhoAmIResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhoAmI" } } }, "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "readyz: postgres, clickhouse, and finance_db / legal_db when configured." } } }, "CandlesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/candles.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FundingRatesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/funding_rates.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "OpenInterestResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/open_interest.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "InstrumentsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/instruments.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "TickersResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/tickers_latest.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "CalendarEventsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/calendar_events.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "MacroSeriesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/macro_series.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "MacroObservationsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/macro_observation.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "MacroDerivedSeriesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/macro_derived_series.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "MacroDerivedObservationsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/macro_derived_observation.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsCompaniesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_company.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsFilingsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_filing.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsFactsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_fact.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsFundamentalsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_fundamental.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsInsiderTransactionsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_insider_transaction.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsFailsToDeliverResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_ftd.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsHoldings13fResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_holding_13f.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsNews8kResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_news_8k.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FilingsCongressTradesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/filings_congress_trade.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwSecuritiesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_securities.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwDailyCloseResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_daily_close.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwValuationDailyResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_valuation_daily.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwInstitutionalDailyResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_institutional_daily.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwMarginDailyResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_margin_daily.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwMonthlyRevenueResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_monthly_revenue.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwStatementsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_statements.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwIndicesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_indices.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EquitiesTwSourcesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/equities_tw_sources.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "StatuteInstrumentsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteInstrument" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "StatuteDetailResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "#/components/schemas/StatuteDetail" }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": "null" } } }, "StatuteProvisionsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatuteProvision" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] }, "next_from_seq": { "type": [ "integer", "null" ], "description": "seq of the next page's first provision; set together with next_cursor." } } }, "RegulatoryEntriesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/legal_regulatory_entry.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "RegulatoryEntryResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "#/components/schemas/RegulatoryEntry" }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": "null" } } }, "FscNewsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/legal_fsc_news_item.json" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "RegulatoryEntry": { "description": "A list entry with all its names and attributes.", "allOf": [ { "$ref": "https://docs.aggre.org/schemas/legal_regulatory_entry.json" }, { "type": "object", "required": [ "names", "attributes" ], "properties": { "names": { "type": "array", "items": { "type": "object" } }, "attributes": { "type": "array", "items": { "type": "object" } } } } ] }, "HealthMeta": { "type": "object", "description": "Meta of every health route. `status` is `empty` when nothing was ever read successfully or this page has no rows; `stale` when our newest successful read is older than the dataset's window (our clock, not the publisher's). `license` and `attribution` are exactly what a person recorded after reading the publisher's terms and are `null` until then; `message` says so. Families add keys of their own (listed per route); clients must ignore keys they do not know.", "required": [ "dataset_id", "status", "fetchedAt", "lastReadAt", "terms_url", "terms_read_on", "license", "attribution" ], "properties": { "dataset_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "stale", "empty", "backfilling", "not_loaded", "degraded" ], "description": "`backfilling` (trials, openFDA): the first full read has not completed (trials: of the registry; openFDA: partitions of the endpoint are still pending), so the list is a part of the data. `not_loaded` (NPPES only): no monthly baseline has been applied. `degraded` (NPPES: a stretch of weekly changes was never published to us and no later baseline has repaired it; openFDA: nothing is pending but some partitions failed to import and wait for a person, so the rows are incomplete)." }, "fetchedAt": { "type": "string", "format": "date-time" }, "lastReadAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End of our newest successful run." }, "terms_url": { "type": [ "string", "null" ] }, "terms_read_on": { "type": "string", "format": "date", "description": "Always set on a served answer: without it the route is 503 terms_unread." }, "license": { "type": [ "string", "null" ] }, "attribution": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } } }, "OnchainMeta": { "type": "object", "description": "Meta of the on-chain routes. `status` is `empty` when nothing was ever read successfully or this page has no rows; `stale` when the answer follows the newest data and our newest successful read is older than the dataset's window (our clock, not the publisher's); a view pinned to a date (`as_of`, `from`, `to`) is a fact and is `ok`. `dataset.credit` and `dataset.license` are exactly what a person recorded after reading the publisher's terms: whoever shows a row shows the credit. Clients must ignore keys they do not know.", "required": [ "source", "dataset_id", "also_in", "status", "fetchedAt", "lastReadAt", "dataDate", "message", "dataset" ], "properties": { "source": { "type": "string", "description": "The source id, today `defillama`." }, "dataset_id": { "type": "string", "enum": [ "onchain.defi.protocol_tvl" ] }, "also_in": { "type": "array", "items": { "type": "string" }, "description": "Other dataset ids this dataset is also listed under (`finance.market`). A pointer only: the data is served here." }, "status": { "type": "string", "enum": [ "ok", "stale", "empty" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "lastReadAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When our newest successful read of the source finished." }, "dataDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Midnight UTC of the newest `as_of` among the returned rows." }, "message": { "type": [ "string", "null" ] }, "dataset": { "type": "object", "required": [ "title", "terms_url", "terms_read_on", "credit", "license" ], "properties": { "title": { "type": "string" }, "terms_url": { "type": [ "string", "null" ] }, "terms_read_on": { "type": "string", "format": "date", "description": "Always set on a served answer: without it the route is 503 terms_unread." }, "credit": { "type": [ "string", "null" ], "description": "The attribution the terms ask for, as a person recorded it." }, "license": { "type": [ "string", "null" ] } } } } }, "OnchainProtocolTvlResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/onchain_protocol_tvl.json" } }, "meta": { "$ref": "#/components/schemas/OnchainMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EmaMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "report": { "type": [ "object", "null" ], "description": "The newest report file read: `meta` (the lines above its header, as EMA wrote them, including its own generated-on text, unparsed), `rows`, `headers_missing`, `first_read_at`, `last_read_at`, `source_url`." } } } ] }, "EmaMedicinesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_ema_medicine.json" } }, "meta": { "$ref": "#/components/schemas/EmaMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EmaMedicineResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_ema_medicine.json" }, "meta": { "$ref": "#/components/schemas/EmaMeta" }, "next_cursor": { "type": "null" } } }, "NppesMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "load": { "type": "object", "description": "What has been applied: `baseline_loaded`, `baseline_file`, `baseline_applied_at`, `last_weekly_period_end` (last day covered by the newest weekly file), `open_gaps` (a count) and `gaps` (`from`, `to` of each stretch of weekly changes never published to us and not yet repaired by a new baseline)." } } } ] }, "NppesProvidersResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_nppes_provider.json" } }, "meta": { "$ref": "#/components/schemas/NppesMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "NppesProviderResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_nppes_provider.json" }, "meta": { "$ref": "#/components/schemas/NppesMeta" }, "next_cursor": { "type": "null" } } }, "TrialsMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "walk": { "type": [ "object", "null" ], "description": "How far the worker's walks of the registry have got (dates, null where not reached): `full_watermark` (highest first-post date consumed by the current full walk), `walk_started_on`, `full_complete_on` (the day the last covered full walk began; null until one has completed), `incremental_watermark`. A study the registry removed is not detected; nothing here claims it was." } } } ] }, "TrialsStudiesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_trials_study.json" } }, "meta": { "$ref": "#/components/schemas/TrialsMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "TrialsStudyResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_trials_study.json" }, "meta": { "$ref": "#/components/schemas/TrialsMeta" }, "next_cursor": { "type": "null" } } }, "FdaSummaryMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "run": { "type": [ "object", "null" ], "description": "The newest finished worker run: `status`, `remaining` (clearances still waiting when that pass ended; null if it did not count) and `finished_at`. `meta.status` is `backfilling` while `remaining` is above zero. `lastReadAt` is the end of the newest `ok` or `partial` run, because the first fill is weeks of partial passes." } } } ] }, "FdaSummariesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_fda_summary.json" } }, "meta": { "$ref": "#/components/schemas/FdaSummaryMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FdaSummaryResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_fda_summary.json" }, "meta": { "$ref": "#/components/schemas/FdaSummaryMeta" }, "next_cursor": { "type": "null" } } }, "FdaMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "required": [ "endpoint", "export_date", "manifest_export_date", "partitions" ], "properties": { "endpoint": { "type": "string", "description": "The openFDA endpoint of the dataset, as the manifest spells it (`device/pma`)." }, "export_date": { "type": [ "string", "null" ], "format": "date", "description": "The newest export we have imported for the endpoint (null: none yet). A row whose own `export_date` is older has `in_latest_export: false`." }, "manifest_export_date": { "type": [ "string", "null" ], "format": "date", "description": "The newest export the manifest announced. It differs from `export_date` while a new export is being imported." }, "partitions": { "type": "object", "required": [ "total", "imported", "pending", "failed", "skipped" ], "description": "The endpoint's partition files by state. `pending` means an import is in progress (`meta.status` is `backfilling`); `failed` means stuck until a person resets it (`degraded`); `skipped` is held on purpose (e.g. `drug/label` until its storage question is settled).", "properties": { "total": { "type": "integer" }, "imported": { "type": "integer" }, "pending": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" } } } } } ] }, "FdaRecordsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_fda_record.json" } }, "meta": { "$ref": "#/components/schemas/FdaMeta" }, "next_cursor": { "type": [ "string", "null" ], "description": "Present while more follow, including after a page cut short by the size budget." } } }, "FdaRecordResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_fda_record.json" }, "meta": { "$ref": "#/components/schemas/FdaMeta" }, "next_cursor": { "type": "null" } } }, "WhoMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "indicator": { "type": "object", "description": "The indicator asked for, as in the catalogue (including when its last complete read ended)." }, "spatial_dim_type": { "type": "string" }, "descriptions": { "type": "string", "description": "On the catalogue: the descriptions are Aggre's own words." } } } ] }, "WhoObservationsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_who_observation.json" } }, "meta": { "$ref": "#/components/schemas/WhoMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "WhoIndicatorsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_who_indicator.json" } }, "meta": { "$ref": "#/components/schemas/WhoMeta" }, "next_cursor": { "type": "null" } } }, "EurostatMeta": { "allOf": [ { "$ref": "#/components/schemas/HealthMeta" }, { "type": "object", "properties": { "years": { "type": "array", "description": "What the worker recorded for each year it has read: `year`, `source_updated` (the dataset's own `updated` text, verbatim), `rows`, `cells_dropped`, `flags_held`, `read_at`.", "items": { "type": "object" } } } } ] }, "EurostatMortalityResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_eurostat_mortality.json" } }, "meta": { "$ref": "#/components/schemas/EurostatMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EurostatCellResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "https://docs.aggre.org/schemas/health_eurostat_mortality.json" }, "meta": { "$ref": "#/components/schemas/EurostatMeta" }, "next_cursor": { "type": "null" } } }, "EurostatCausesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_eurostat_cause.json" } }, "meta": { "$ref": "#/components/schemas/EurostatMeta" }, "next_cursor": { "type": "null" } } }, "EurostatPlacesResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/health_eurostat_place.json" } }, "meta": { "$ref": "#/components/schemas/EurostatMeta" }, "next_cursor": { "type": "null" } } }, "ContractMeta": { "type": "object", "description": "Meta of the standard-form routes. `status` is `empty` when the dataset was never read successfully or this page has no rows, `stale` when our newest successful read is older than 14 days (our clock; it wins over an empty page). `license` and `attribution` are exactly what a person recorded after reading the publisher's terms and are `null` until then; the route is 503 `terms_unread` before that. `message` always says the text is machine-extracted and may contain errors.", "required": [ "dataset_id", "status", "fetchedAt", "lastReadAt", "terms_url", "terms_read_on", "license", "attribution", "message" ], "properties": { "dataset_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "stale", "empty" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "lastReadAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End of our newest `ok` run." }, "terms_url": { "type": [ "string", "null" ] }, "terms_read_on": { "type": "string", "format": "date", "description": "Always set on a served answer: without it the route is 503 terms_unread." }, "license": { "type": [ "string", "null" ] }, "attribution": { "type": [ "string", "null" ] }, "message": { "type": "string" } } }, "ContractFormsResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "https://docs.aggre.org/schemas/legal_contract_form.json" } }, "meta": { "$ref": "#/components/schemas/ContractMeta" }, "next_cursor": { "type": [ "string", "null" ] } } }, "ContractFormResponse": { "type": "object", "required": [ "data", "meta", "next_cursor" ], "properties": { "data": { "$ref": "#/components/schemas/ContractForm" }, "meta": { "$ref": "#/components/schemas/ContractMeta" }, "next_cursor": { "type": "null" } } }, "ContractForm": { "description": "A standard form with its versions and the files (and text) of the shown version.", "allOf": [ { "$ref": "https://docs.aggre.org/schemas/legal_contract_form.json" }, { "type": "object", "required": [ "version", "shown_version", "versions", "attachments" ] } ] } } }, "paths": { "/healthz": { "get": { "tags": [ "meta" ], "operationId": "healthz", "summary": "Liveness", "description": "No auth. The process is up; nothing is checked.\n", "security": [], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/readyz": { "get": { "tags": [ "meta" ], "operationId": "readyz", "summary": "Readiness", "description": "No auth. Postgres and ClickHouse answer (and `finance_db` / `legal_db` when configured). `503` with the same body shape when one does not.\n", "security": [], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/datasets": { "get": { "tags": [ "meta" ], "operationId": "listDatasets", "summary": "The datasets and where to read them", "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/whoami": { "get": { "tags": [ "meta" ], "operationId": "whoami", "summary": "The calling key and its usage", "description": "Never returns the secret. Counts as a normal request against the key.\n", "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmIResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/candles_1m": { "get": { "tags": [ "market" ], "operationId": "candles1M", "summary": "Confirmed one-minute candles of one instrument", "description": "Only confirmed bars. `ts` is the bar open (Unix ms UTC). **No cursor paging yet:** `next_cursor` is always null; read further with `from`/`to`. Dataset `finance.market.candles_1m`; semantics in [the dataset guide](https://docs.aggre.org/datasets).\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentId" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderDesc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/candles_1h": { "get": { "tags": [ "market" ], "operationId": "candles1H", "summary": "Confirmed one-hour candles of one instrument", "description": "Only confirmed bars. `ts` is the bar open (Unix ms UTC). **No cursor paging yet:** `next_cursor` is always null; read further with `from`/`to`. Dataset `finance.market.candles_1h`; semantics in [the dataset guide](https://docs.aggre.org/datasets).\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentId" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderDesc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/candles_1d": { "get": { "tags": [ "market" ], "operationId": "candles1D", "summary": "Confirmed one-day candles of one instrument", "description": "Only confirmed bars. `ts` is the bar open (Unix ms UTC). **No cursor paging yet:** `next_cursor` is always null; read further with `from`/`to`. Dataset `finance.market.candles_1d`; semantics in [the dataset guide](https://docs.aggre.org/datasets).\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentId" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderDesc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/funding_rates": { "get": { "tags": [ "market" ], "operationId": "fundingRates", "summary": "Settled funding payments of a perpetual", "description": "`instrument_id` must be a PERP or FUTURES id. `rate` is that period's fraction as the venue reports it, not annualised. `next_cursor` is always null. Stale after 24 h. Dataset `finance.market.funding_rates`.\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentId" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderDesc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingRatesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/open_interest": { "get": { "tags": [ "market" ], "operationId": "openInterest", "summary": "Open-interest snapshots of a perpetual", "description": "`instrument_id` must be a PERP or FUTURES id. A snapshot in base-asset units; history starts the day collection starts. `next_cursor` is always null. Stale after 30 min. Dataset `finance.market.open_interest`.\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentId" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderDesc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenInterestResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/instruments": { "get": { "tags": [ "market" ], "operationId": "listInstruments", "summary": "The instrument list", "description": "Dataset `finance.market.instruments` (Postgres). No cursor. 503 `store_unavailable` when `finance_db` is not configured.\n", "parameters": [ { "$ref": "#/components/parameters/Venue" }, { "$ref": "#/components/parameters/Product" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/market/tickers": { "get": { "tags": [ "market" ], "operationId": "listTickers", "summary": "The latest ticker of every enabled instrument", "description": "One row per enabled instrument, latest only: no history, no cursor. The 24 h figures are the venue's rolling 24 hours and null where the venue does not send them. Dataset `finance.market.tickers_latest`.\n", "parameters": [ { "$ref": "#/components/parameters/Venue" }, { "$ref": "#/components/parameters/Product" }, { "name": "instrument_id", "in": "query", "description": "Exact; must agree with `venue`/`product` when they are given.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TickersResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/macro/calendar_events": { "get": { "tags": [ "macro" ], "operationId": "listCalendarEvents", "summary": "Scheduled economic releases", "description": "The schedule only: no estimates, no actual or previous values. `impact` is Aggre's own grading. Whoever shows an event shows its `credit`. `next_cursor` is always null. Dataset `finance.macro.calendar_events`.\n", "parameters": [ { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "BLS", "BEA", "CENSUS", "FOMC", "ECB", "ONS", "EUROSTAT" ] } }, { "name": "economy", "in": "query", "description": "Two uppercase letters; EU = euro area.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "$ref": "#/components/parameters/Limit1000" }, { "$ref": "#/components/parameters/OrderAsc" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/macro/series": { "get": { "tags": [ "macro" ], "operationId": "listMacroSeries", "summary": "The macro series catalogue", "description": "Ordered by `series_id`. Dataset `finance.macro.series`.\n", "parameters": [ { "name": "source", "in": "query", "description": "Lowercase letters, digits and underscores.", "schema": { "type": "string" } }, { "name": "economy", "in": "query", "description": "Two uppercase letters; EU = euro area.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "frequency", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "annual", "irregular" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroSeriesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/macro/observations": { "get": { "tags": [ "macro" ], "operationId": "listMacroObservations", "summary": "Observations of one series", "description": "A revision is a new `version`, never an overwrite. `value x unit_multiplier` is in `unit`. Whoever shows a value shows its `credit`. `meta.series` is the series row. Dataset `finance.macro.observations`.\n", "parameters": [ { "name": "series_id", "in": "query", "required": true, "description": "e.g. fed.effr; list them at /v1/finance/macro/series. An unknown id is 404.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "YYYY-MM-DD on `period`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "YYYY-MM-DD on `period`, exclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "as_of", "in": "query", "description": "Unix ms: each period as Aggre knew it then (the highest version first seen at or before it).", "schema": { "type": "integer", "format": "int64" } }, { "name": "versions", "in": "query", "description": "`latest` = highest version per period; `all` = every revision.", "schema": { "type": "string", "enum": [ "latest", "all" ], "default": "latest" } }, { "$ref": "#/components/parameters/OrderAsc" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroObservationsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/macro_derived/series": { "get": { "tags": [ "macro" ], "operationId": "listMacroDerivedSeries", "summary": "The computed macro series catalogue", "description": "Series Aggre computes on read; nothing is stored: the year-over-year change of 30 stored series (`twtrade`, `twdgbas`), ten sums and ratios over the rows of the FSC Banking Bureau's issuer and bank files, five sums, counts and medians over the exchange's monthly revenue file (`twfsc.*`), fourteen monthly series of counted deals and median price per ping from the Ministry of the Interior's actual-price registry (`twrealprice.*`), the Treasury's monthly interest expense on public issues (`fiscal.interest_expense_public`, the sum of the 29 stored `fiscal.ie_*` lines; `rows_used` counts the lines present) and, for every CFTC contract whose long, short and open-interest series are stored, the net position (long - short, `cftc._net`) and its share of open interest in percent (`cftc.`). Listed only while what it is computed from exists, and, for rows of an entity dataset, only once somebody has read the publisher's terms. Same filters as the stored catalogue; `inputs` and `formula` say what each is computed from. Ordered by `series_id`. Dataset `finance.macro_derived.series`.\n", "parameters": [ { "name": "source", "in": "query", "description": "Lowercase letters, digits and underscores.", "schema": { "type": "string" } }, { "name": "economy", "in": "query", "description": "Two uppercase letters; EU = euro area.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "frequency", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "annual", "irregular" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroDerivedSeriesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/macro_derived/observations": { "get": { "tags": [ "macro" ], "operationId": "listMacroDerivedObservations", "summary": "Computed values of one series", "description": "`value x unit_multiplier` is in `unit`. A year-over-year value (percent) is the input's change against the same period one year earlier (`compared_with`), from the newest stored version of both; a value over rows carries `rows_used`, how many issuers, banks, companies or deals it is computed from; a `twrealprice` value carries `provisional`, true for the latest three months published. A revised input revises the value on the next read. A period with nothing to compute from has no row. Whoever shows a value shows its `credit`. `meta.series` is the computed series row; `meta.status` follows what it is computed from. 404 `not_found` for an id that is not computed from anything read yet; 503 `terms_unread` for one over an entity dataset whose publisher terms nobody has read. Dataset `finance.macro_derived.observations`.\n", "parameters": [ { "name": "series_id", "in": "query", "required": true, "description": "e.g. twtrade.exports_yoy; list them at /v1/finance/macro_derived/series. An unknown id is 404.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "YYYY-MM-DD on `period`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "YYYY-MM-DD on `period`, exclusive.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/OrderAsc" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroDerivedObservationsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/companies": { "get": { "tags": [ "filings" ], "operationId": "listFilingsCompanies", "summary": "SEC companies on the coverage list", "description": "Ordered by `cik`. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "$ref": "#/components/parameters/Cik" }, { "name": "ticker", "in": "query", "description": "Letters, digits, `.` or `-`, at most 12; case-insensitive.", "schema": { "type": "string" } }, { "name": "sic", "in": "query", "description": "Standard Industrial Classification code.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsCompaniesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/filings": { "get": { "tags": [ "filings" ], "operationId": "listFilings", "summary": "A company's filings", "description": "Ordered by `filed_on`, `accession`. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "$ref": "#/components/parameters/CikRequired" }, { "name": "form", "in": "query", "description": "Comma list of at most 20 form names, e.g. 10-K,8-K.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "YYYY-MM-DD on `filed_on`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "YYYY-MM-DD on `filed_on`, exclusive.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/OrderDesc" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsFilingsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/company_facts": { "get": { "tags": [ "filings" ], "operationId": "listFilingsCompanyFacts", "summary": "As-filed XBRL facts of a company", "description": "Facts are as filed, never overwritten; `value` is a decimal string. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "$ref": "#/components/parameters/CikRequired" }, { "name": "concept", "in": "query", "description": "Comma list of at most 20 concept names, e.g. Revenues,Assets.", "schema": { "type": "string" } }, { "name": "unit", "in": "query", "schema": { "type": "string" } }, { "name": "period_from", "in": "query", "description": "YYYY-MM-DD on the period end, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "period_to", "in": "query", "description": "YYYY-MM-DD on the period end, exclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "fiscal_year", "in": "query", "description": "The filing's own label.", "schema": { "type": "integer" } }, { "name": "fiscal_period", "in": "query", "schema": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3", "Q4" ] } }, { "name": "latest", "in": "query", "description": "`true` (default): the latest-filed value of each period; `false`: every filed value.", "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsFactsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/fundamentals": { "get": { "tags": [ "filings" ], "operationId": "listFilingsFundamentals", "summary": "Normalized fundamentals per fiscal period", "description": "Computed by Aggre's normalizer from as-filed facts, not published by the SEC (`meta.message` says how). No cursor. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "$ref": "#/components/parameters/CikRequired" }, { "name": "fiscal_period", "in": "query", "description": "`FY` or `Q` (any quarter).", "schema": { "type": "string", "enum": [ "FY", "Q" ] } }, { "name": "limit", "in": "query", "description": "Periods returned, newest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 12 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsFundamentalsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/insider_transactions": { "get": { "tags": [ "filings" ], "operationId": "listFilingsInsiderTransactions", "summary": "Form 4 insider transactions of an issuer", "description": "`cik` is the ISSUER's. Newest transaction first. `price` is a decimal string, `shares` and `owned_after` are numbers; names of people are served as filed. [the filings guide](https://docs.aggre.org/datasets/filings) (and section 6.5 for the caveats).\n", "parameters": [ { "$ref": "#/components/parameters/CikRequired" }, { "name": "from", "in": "query", "description": "YYYY-MM-DD on `transaction_date`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "YYYY-MM-DD on `transaction_date`, exclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "code", "in": "query", "description": "One capital letter: the Form 4 transaction code, e.g. P (purchase) or S (sale).", "schema": { "type": "string", "pattern": "^[A-Z]$" } }, { "name": "amendments", "in": "query", "description": "`collapse`: a line a later 4/A of the same filer restates unchanged is shown once; `all`: every line.", "schema": { "type": "string", "enum": [ "collapse", "all" ], "default": "collapse" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsInsiderTransactionsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/fails_to_deliver": { "get": { "tags": [ "filings" ], "operationId": "listFilingsFailsToDeliver", "summary": "SEC fails-to-deliver balances of a symbol", "description": "The aggregate net balance of shares that failed to be delivered, by settlement date; a fail can arise on a long or a short sale and is not evidence of abusive or naked short selling (`meta.message` says so). `quantity` is an integer, `price` the SEC's previous-day close as a decimal string. No CUSIP is stored or served. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "The ticker symbol, upper-cased by the API: 1 to 15 of letters, digits, `.` and `-`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,15}$" } }, { "name": "from", "in": "query", "description": "YYYY-MM-DD on `settlement_date`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "YYYY-MM-DD on `settlement_date`, exclusive.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/OrderDesc" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsFailsToDeliverResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/holdings_13f": { "get": { "tags": [ "filings" ], "operationId": "listFilingsHoldings13f", "summary": "SEC Form 13F holdings of a covered company", "description": "One institution's holding of the company in one quarter, from the SEC's Form 13F data sets (originals and combination reports; options and bonds left out; the lines of one filing for one issuer summed). **Matched by the issuer's name** (the CUSIP is neither read nor stored), so a row may include another class of the same issuer and a differently spelled one may be missing: `meta.message` always says so. Newest quarter first, the largest holding first within a quarter. `consistent` is false when the reported price (`value_usd` / `shares`) is more than 5 times away from that quarter's median for the stock; such rows are hidden unless `consistent=all`. Give `ticker` or `issuer_cik`, not both. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "name": "ticker", "in": "query", "description": "A coverage ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12. Give this or `issuer_cik`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,12}$" } }, { "name": "issuer_cik", "in": "query", "description": "The issuer's CIK, with or without leading zeros; returned padded to ten digits. Give this or `ticker`.", "schema": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, { "name": "period", "in": "query", "description": "A quarter end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "consistent", "in": "query", "description": "`true` (default) hides rows whose price is out of line; `all` shows them too.", "schema": { "type": "string", "enum": [ "true", "all" ], "default": "true" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsHoldings13fResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/news_8k": { "get": { "tags": [ "filings" ], "operationId": "listFilingsNews8k", "summary": "SEC 8-K current reports of a covered company, with the file names of their press releases", "description": "The company's 8-K and 8-K/A reports, newest first, with their items and, where the report came with a press release, the Exhibit 99 documents' file names and the company's own short descriptions (an `EX-99.1` description that only repeats the type is `null`). **No text of a release or of any filing is stored or served**: open `url` (the report on EDGAR) or the exhibit's file in the same EDGAR folder. `exhibits_complete` is false while the report may carry a release (items 2.02, 7.01, 8.01) and its EDGAR header page has not been read yet (the worker reads at most 5 per company per day and 200 per hour, and gives up on a page after 5 tries); a report that cannot carry one is complete with no exhibits. Reports filed before the worker's window (90 days by default) are listed but were never asked about. Give `cik` or `ticker`, not both. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "name": "cik", "in": "query", "description": "The company's CIK, with or without leading zeros; returned padded to ten digits. Give this or `ticker`.", "schema": { "type": "string", "pattern": "^[0-9]{1,10}$" } }, { "name": "ticker", "in": "query", "description": "A coverage ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12. Give this or `cik`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,12}$" } }, { "name": "from", "in": "query", "description": "First filing day (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last filing day (exclusive), YYYY-MM-DD; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "item", "in": "query", "description": "Only reports that list this 8-K item number, e.g. `2.02` (results of operations), `7.01` (Regulation FD), `8.01` (other events).", "schema": { "type": "string", "pattern": "^[0-9]{1,2}\\.[0-9]{2}$" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsNews8kResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/filings/congress_trades": { "get": { "tags": [ "filings" ], "operationId": "listFilingsCongressTrades", "summary": "Stock trades of US members of Congress (Periodic Transaction Reports)", "description": "Stock trades that members of Congress reported under the STOCK Act, newest trade first. **Disclosed weeks after the trade**: `transaction_date` is the trade, `disclosure_date` the day it was reported. **Amounts are the value ranges the report uses** (`amount_low`, `amount_high`, and the text as filed), never the size of a trade; `owner` says whose trade it is (a spouse's or a child's too). Rows with `source` `senate_stock_watcher` are a community aggregate's reading of the Senate's reports, not the Senate's own data. Use of financial disclosure reports is restricted by law and whether that bears on this service has not been reviewed; the dataset is off until a person has read its source's terms, and `meta.message` says so while they are unread. Not a recommendation. `meta.source` is the rows' source when they share one, else `aggre`; `meta.dataset.sources` lists the terms of each source in the page. The API records the dataset asked for, never the query. [the filings guide](https://docs.aggre.org/datasets/filings).\n", "parameters": [ { "name": "politician", "in": "query", "description": "Case-insensitive substring of the member's name, 2 to 100 characters; percent, underscore and backslash are literal.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "ticker", "in": "query", "description": "Exact ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,12}$" } }, { "name": "chamber", "in": "query", "description": "Only this chamber.", "schema": { "type": "string", "enum": [ "Senate", "House" ] } }, { "name": "type", "in": "query", "description": "Only this kind of transaction (`transaction_type`).", "schema": { "type": "string", "enum": [ "buy", "sell", "exchange" ] } }, { "name": "from", "in": "query", "description": "First transaction day (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last transaction day (exclusive), YYYY-MM-DD; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "disclosed_from", "in": "query", "description": "First disclosure day (inclusive), YYYY-MM-DD; rows without a disclosure date never match.", "schema": { "type": "string", "format": "date" } }, { "name": "disclosed_to", "in": "query", "description": "Last disclosure day (exclusive), YYYY-MM-DD; must be after `disclosed_from`.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsCongressTradesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/securities": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwSecurities", "summary": "Taiwan listed and OTC securities", "description": "The catalogue of TWSE and TPEx securities, ordered by `security_id`. `q` matches a code prefix or a name substring (at most 20 characters; `%`, `_` and `\\` are literal). Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "market", "in": "query", "description": "Only this exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "q", "in": "query", "description": "Code prefix or name substring.", "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "industry_code", "in": "query", "description": "Two-digit industry code, e.g. 24.", "schema": { "type": "string", "pattern": "^[0-9]{2}$" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwSecuritiesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/daily_close": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwDailyClose", "summary": "Daily close of Taiwan securities", "description": "Open, high, low, close, volume and value of a trading day. Either `security_id` (one security's history) or `date` (every security of the day), not both. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history, e.g. TWSE:2330. Give this or `date`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "date", "in": "query", "description": "Every security of this trading day, YYYY-MM-DD. Give this or `security_id`.", "schema": { "type": "string", "format": "date" } }, { "name": "market", "in": "query", "description": "Narrows a `date` query to one exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "from", "in": "query", "description": "First trading day (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last trading day (exclusive) of a history; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwDailyCloseResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/valuation_daily": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwValuationDaily", "summary": "Daily valuation ratios of Taiwan securities", "description": "P/E, dividend yield and P/B of a trading day. Either `security_id` (one security's history) or `date` (every security of the day), not both. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history, e.g. TWSE:2330. Give this or `date`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "date", "in": "query", "description": "Every security of this trading day, YYYY-MM-DD. Give this or `security_id`.", "schema": { "type": "string", "format": "date" } }, { "name": "market", "in": "query", "description": "Narrows a `date` query to one exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "from", "in": "query", "description": "First trading day (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last trading day (exclusive) of a history; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwValuationDailyResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/institutional_daily": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwInstitutionalDaily", "summary": "Institutional trades of TPEx securities", "description": "Foreign, investment-trust and dealer net trades of a trading day. **TPEx securities only**: the TWSE file is not read. Either `security_id` (one security's history) or `date` (every security of the day), not both. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history, e.g. TWSE:2330. Give this or `date`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "date", "in": "query", "description": "Every security of this trading day, YYYY-MM-DD. Give this or `security_id`.", "schema": { "type": "string", "format": "date" } }, { "name": "market", "in": "query", "description": "Narrows a `date` query to one exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "from", "in": "query", "description": "First trading day (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last trading day (exclusive) of a history; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwInstitutionalDailyResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/margin_daily": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwMarginDaily", "summary": "Margin balances of TPEx securities", "description": "Margin and short balances of a trading day, in lots as published. **TPEx securities only**: the TWSE file (11680) is not read. Either `security_id` (one security's history) or `date` (every security of the day), not both. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history, e.g. TWSE:2330. Give this or `date`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "date", "in": "query", "description": "Every security of this trading day, YYYY-MM-DD. Give this or `security_id`.", "schema": { "type": "string", "format": "date" } }, { "name": "market", "in": "query", "description": "Narrows a `date` query to one exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "from", "in": "query", "description": "First trading day (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last trading day (exclusive) of a history; must be after `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwMarginDailyResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/monthly_revenue": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwMonthlyRevenue", "summary": "Monthly revenue of Taiwan companies", "description": "A company's revenue for one month, in thousand NT$ as published. A revised figure is a new version; `versions=all` and `as_of` serve the history. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history. Give this or `month`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "month", "in": "query", "description": "Every security of this month, the first day, YYYY-MM-01. Give this or `security_id`.", "schema": { "type": "string", "format": "date" } }, { "name": "from", "in": "query", "description": "First month (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last month (exclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "versions", "in": "query", "description": "`latest` (default) or every stored version.", "schema": { "type": "string", "enum": [ "latest", "all" ] } }, { "name": "as_of", "in": "query", "description": "What Aggre knew at this Unix time in milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwMonthlyRevenueResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/statements": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwStatements", "summary": "Quarterly statements of Taiwan companies", "description": "Income statements and balance sheets in the six industry formats, amounts in thousand NT$ as published. A revised figure is a new version. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "security_id", "in": "query", "description": "One security's history. Give this or `fiscal_year` with `quarter`.", "schema": { "type": "string", "pattern": "^(TWSE|TPEX):[0-9A-Z]+$" } }, { "name": "fiscal_year", "in": "query", "description": "With `quarter`: every security of that quarter.", "schema": { "type": "integer", "minimum": 1990 } }, { "name": "quarter", "in": "query", "description": "With `fiscal_year`.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 } }, { "name": "statement", "in": "query", "description": "Only this statement.", "schema": { "type": "string", "enum": [ "income", "balance" ] } }, { "name": "format", "in": "query", "description": "Only this industry format.", "schema": { "type": "string", "enum": [ "ci", "basi", "bd", "fh", "ins", "mim" ] } }, { "name": "from", "in": "query", "description": "First period (inclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last period (exclusive) of a history.", "schema": { "type": "string", "format": "date" } }, { "name": "versions", "in": "query", "description": "`latest` (default) or every stored version.", "schema": { "type": "string", "enum": [ "latest", "all" ] } }, { "name": "as_of", "in": "query", "description": "What Aggre knew at this Unix time in milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwStatementsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/indices": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwIndices", "summary": "Index closes of Taiwan exchanges", "description": "Close of each exchange index of a trading day. Give `market` or `index_name` (or both). Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "market", "in": "query", "description": "Only this exchange. Give this or `index_name`.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "index_name", "in": "query", "description": "Exact index name. Give this or `market`.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "from", "in": "query", "description": "First trading day (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last trading day (exclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Sort direction (default: newest first for a history, `security_id` order for a day).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwIndicesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/finance/equities_tw/sources": { "get": { "tags": [ "equities_tw" ], "operationId": "listEquitiesTwSources", "summary": "Registered upstream files of the Taiwan datasets", "description": "The registered files with their licence, the terms state (`terms_read_on`) and when each was last read. Every response carries `meta.attribution` (`[{source_id, credit}]`): whoever shows a row shows its credit. [the Taiwan equities guide](https://docs.aggre.org/datasets/taiwan-equities).\n", "parameters": [ { "name": "market", "in": "query", "description": "Only this exchange.", "schema": { "type": "string", "enum": [ "TWSE", "TPEX" ] } }, { "name": "kind", "in": "query", "description": "Only this kind of file.", "schema": { "type": "string", "enum": [ "valuation", "institutional", "margin", "close", "index", "revenue", "income", "balance", "profile" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquitiesTwSourcesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/statutes/instruments": { "get": { "tags": [ "legal" ], "operationId": "listStatuteInstruments", "summary": "Statutes across the ten statute datasets", "description": "Ordered by `instrument_id`; the list has no provisions and no foreword. `meta.restricted` / `attribution` / `licenses` carry the terms the data comes with. [the statutes guide](https://docs.aggre.org/datasets/legal-statutes).\n", "parameters": [ { "$ref": "#/components/parameters/StatuteDataset" }, { "name": "jurisdiction", "in": "query", "description": "Two uppercase letters, e.g. TW, EU.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "language", "in": "query", "description": "Exact, e.g. zh-Hant, en, ja.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "act", "regulation", "order", "treaty", "other" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "in_force", "repealed", "abandoned", "withdrawn" ] } }, { "name": "q", "in": "query", "description": "Title contains this text (case-insensitive, 1-200 characters). A catalogue filter, not full-text search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "updated_since", "in": "query", "description": "YYYY-MM-DD (00:00 UTC) or RFC 3339; `updated_at >=` this.", "schema": { "type": "string" } }, { "name": "include_removed", "in": "query", "description": "`true` also returns instruments the source stopped listing.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatuteInstrumentsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/statutes/instruments/{instrument_id}": { "get": { "tags": [ "legal" ], "operationId": "getStatuteInstrument", "summary": "One statute with its provisions", "description": "At most 5000 provisions; longer ones set `provisions_truncated` and `next_from_seq`, continue with the provisions route. A removed instrument still answers 200 with `removed_on`. Takes no query parameters. [the statutes guide](https://docs.aggre.org/datasets/legal-statutes).\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentIdPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatuteDetailResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/statutes/instruments/{instrument_id}/provisions": { "get": { "tags": [ "legal" ], "operationId": "listStatuteProvisions", "summary": "The provisions of one statute, paged", "description": "[the statutes guide](https://docs.aggre.org/datasets/legal-statutes). A `from_seq` past the last provision answers 200 with an empty list.\n", "parameters": [ { "$ref": "#/components/parameters/InstrumentIdPath" }, { "name": "version", "in": "query", "description": "Read this version of the text (see `versions` on the instrument). Repeat it on the next page. Not with `as_of`. 404 when there is no such version.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "as_of", "in": "query", "description": "Read the text Aggre held at this date or RFC 3339 time (encode `+` as %2B). Not with `version`. 404 before the history begins.", "schema": { "type": "string" } }, { "name": "from_seq", "in": "query", "description": "Start at this `seq` (default 0). Give this or `cursor`, not both.", "schema": { "type": "integer", "minimum": 0 } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "number", "in": "query", "description": "An article number: the raw text as stored (`第 184 條`, `Article 15-1`, matched exactly) or its article key (`184`, `184-1`, `184之1`, `第184條之1`, `Article 184`; leading zeros ignored), which matches every provision whose number has the same key. `184` does not match `184-1`. The returned `number` is the raw text. [the statutes guide](https://docs.aggre.org/datasets/legal-statutes).", "example": "184-1", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatuteProvisionsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/regulatory/entries": { "get": { "tags": [ "legal" ], "operationId": "listRegulatoryEntries", "summary": "Entries of a sanctions or exclusion list", "description": "Served as published. [the regulatory guide](https://docs.aggre.org/datasets/legal-regulatory); `meta.message` carries the terms status.\n", "parameters": [ { "$ref": "#/components/parameters/RegulatoryDatasetRequired" }, { "name": "q", "in": "query", "description": "Name search on the normalized name key (letters and digits).", "schema": { "type": "string" } }, { "name": "match", "in": "query", "description": "Only with `q`.", "schema": { "type": "string", "enum": [ "prefix", "exact" ], "default": "prefix" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "person", "entity", "vessel", "aircraft", "other" ] } }, { "name": "listed_from", "in": "query", "description": "YYYY-MM-DD on `listed_on`.", "schema": { "type": "string", "format": "date" } }, { "name": "removed", "in": "query", "description": "Entries the publisher removed: left out (default), included, or only those.", "schema": { "type": "string", "enum": [ "exclude", "include", "only" ], "default": "exclude" } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryEntriesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/regulatory/entry": { "get": { "tags": [ "legal" ], "operationId": "getRegulatoryEntry", "summary": "One entry of a sanctions or exclusion list", "description": "An entry the publisher removed is still found: it carries `removed_on`.\n", "parameters": [ { "$ref": "#/components/parameters/RegulatoryDatasetRequired" }, { "name": "entry_id", "in": "query", "required": true, "description": "The entry id as published (1-256 bytes, no control characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryEntryResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/regulatory/fsc_news": { "get": { "tags": [ "legal" ], "operationId": "listFscNews", "summary": "Taiwan FSC news (five RSS feeds)", "description": "Items of the Financial Supervisory Commission's five official RSS feeds (press releases, penalty cases, announcements, draft-regulation notices, law interpretations), newest first (undated last), then category, then guid. Titles, links and publication days as published; the plain-text `description` only with `include=text` (then `limit` is at most 100). Not the articles behind the links; items that left a feed are kept; no search in V0. `meta.dataset` carries the item count and the per-category counts, `meta.dataDate` the newest publication day, `meta.lastReadAt` our newest successful run; `meta.message` says \"Terms not read\" while nobody has read the FSC's terms. [the regulatory guide](https://docs.aggre.org/datasets/legal-regulatory).\n", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "news", "penalty", "announcement", "draft_law", "law_interp" ] } }, { "name": "published_from", "in": "query", "description": "YYYY-MM-DD on `published_on`, inclusive; an undated item matches neither bound.", "schema": { "type": "string", "format": "date" } }, { "name": "published_to", "in": "query", "description": "YYYY-MM-DD on `published_on`, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "include", "in": "query", "description": "`text` adds the plain-text `description`.", "schema": { "type": "string", "enum": [ "text" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "At most 100 with `include=text`.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FscNewsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/onchain/defi/protocol_tvl": { "get": { "tags": [ "onchain" ], "operationId": "listOnchainProtocolTvl", "summary": "DeFi protocol total value locked", "description": "One row per protocol per UTC day (`as_of` is the day Aggre read the figure; history starts the day the worker first ran, nothing is backfilled). Two shapes, chosen by `slug`. **A day** (no `slug`): every protocol of one day ordered by TVL rank (1 is the largest), the newest stored day unless `as_of` names one; `category` (exact, case-sensitive) and `chain` (one element of `chains`, exact) narrow it; `from`, `to` and `order` are 400 here. **A history** (`slug`): that protocol's rows over time, newest first unless `order=asc`; `from` is inclusive and `to` exclusive, both `YYYY-MM-DD`; `as_of`, `category` and `chain` are 400 there. A cursor pins its day. `tvl_usd` is a JSON number (a double), a figure the source leaves out is `null`, never zero. Whoever shows a row shows `meta.dataset.credit`. `meta.status`: `empty` for no rows, `stale` when the answer follows the newest data and our newest successful read is more than 3 days old, otherwise `ok`. 503 `terms_unread` until a person has read the publisher's terms; the route then reads no row. Dataset `onchain.defi.protocol_tvl`, also listed under `finance.market`. [the on-chain guide](https://docs.aggre.org/datasets/onchain).\n", "parameters": [ { "name": "slug", "in": "query", "description": "One protocol's history, as listed in `slug`: lower-case letters, digits, `.`, `_`, `-`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$" } }, { "name": "as_of", "in": "query", "description": "A day: the UTC day to list, YYYY-MM-DD. Default the newest stored day. Not with `slug`.", "schema": { "type": "string", "format": "date" } }, { "name": "from", "in": "query", "description": "A history: first day (inclusive), YYYY-MM-DD. Needs `slug`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "A history: last day (exclusive), YYYY-MM-DD, after `from`. Needs `slug`.", "schema": { "type": "string", "format": "date" } }, { "name": "category", "in": "query", "description": "A day: only this category, exact as the source writes it (1-100 characters). Not with `slug`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "chain", "in": "query", "description": "A day: only protocols deployed on this chain, exact as the source writes it (1-100 characters). Not with `slug`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "order", "in": "query", "description": "A history: sort direction (default newest first). Needs `slug`; a day is always by rank.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit1000" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnchainProtocolTvlResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/contracts/tw_standard_forms": { "get": { "tags": [ "legal" ], "operationId": "listContractForms", "summary": "Taiwan standard-form contracts (定型化契約), without text", "description": "Model contracts (範本) and the terms a contract must and must not contain (應記載及不得記載事項), as the worker read them from the Executive Yuan's lists, ordered by `form_id`. No text and no attachments here: the single-form route has them. `q` is a literal, case-insensitive title substring. `issuer` is null on a form whose page named no ministry and matches exactly as stored. A form the publisher stopped listing is left out unless `include_removed=true` (it carries `removed_on`). 503 `terms_unread` until a person has read the publisher's terms. [the regulatory guide](https://docs.aggre.org/datasets/legal-regulatory).\n", "parameters": [ { "name": "kind", "in": "query", "description": "`template` = 範本, `required_terms` = 應記載及不得記載事項.", "schema": { "type": "string", "enum": [ "template", "required_terms" ] } }, { "name": "q", "in": "query", "description": "Title contains this text (1-200 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "issuer", "in": "query", "description": "Exactly the stored issuer (1-200 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "published_from", "in": "query", "description": "YYYY-MM-DD, inclusive, on `published_on`.", "schema": { "type": "string", "format": "date" } }, { "name": "published_to", "in": "query", "description": "YYYY-MM-DD, inclusive. Not before `published_from`.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "name": "include_removed", "in": "query", "description": "Also forms the publisher stopped listing.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractFormsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/legal/contracts/tw_standard_forms/{form_id}": { "get": { "tags": [ "legal" ], "operationId": "getContractForm", "summary": "One standard form with its versions and the text of its files", "description": "The form, every version (oldest first) and the files of one version with the text extracted from each. `version` picks an older version (default the current one); `text=false` leaves the text out. The text is machine-extracted and may contain errors, and a scanned file has none (`text_status`): `file_url` is the authoritative document. A removed form is still found (`removed_on`). 404 for an unknown form or version, 400 for an id that is not a GUID, 503 `terms_unread` until a person has read the publisher's terms.\n", "parameters": [ { "$ref": "#/components/parameters/ContractFormIdPath" }, { "name": "version", "in": "query", "description": "A version number from `versions` (default the current one).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "text", "in": "query", "description": "`false` leaves the attachments' text out (default true).", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractFormResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/ema_medicines": { "get": { "tags": [ "health" ], "operationId": "listEmaMedicines", "summary": "EMA medicines register", "description": "Centrally authorised human and veterinary medicines, one row per EMA product number, withdrawn and refused ones included; a medicine the newest report no longer contains has `in_latest_report: false`. Ordered by `(updated_at, product_number)` ascending, so `updated_since` plus the cursor is a change feed. The list leaves out `therapeutic_indication` and `raw` unless `include=text`. 503 `terms_unread` until a person has read EMA's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "category", "in": "query", "description": "Exact, as published (human or veterinary).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Exact, as published (e.g. Authorised, Withdrawn).", "schema": { "type": "string" } }, { "name": "active_substance", "in": "query", "description": "Exact, as published.", "schema": { "type": "string" } }, { "name": "atc_code", "in": "query", "description": "Prefix of the ATC code, 1-7 letters or digits (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{1,7}$" } }, { "name": "therapeutic_area", "in": "query", "description": "Exact, as published.", "schema": { "type": "string" } }, { "name": "accelerated_assessment", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "additional_monitoring", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "advanced_therapy", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "biosimilar", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "conditional_approval", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "exceptional_circumstances", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "generic", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "orphan", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "prime", "in": "query", "description": "Tri-state flag: `true` or `false` matches only rows where the report said Yes or No; blank cells match neither.", "schema": { "type": "boolean" } }, { "name": "authorised_since", "in": "query", "description": "YYYY-MM-DD on `authorisation_date`.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/HealthIncludeText" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000, or 1-200 with `include=text`.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmaMedicinesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/ema_medicines/{product_number}": { "get": { "tags": [ "health" ], "operationId": "getEmaMedicine", "summary": "One EMA medicine, with its text and source row", "description": "Every column, `therapeutic_indication` and `raw` (every cell of the report row) included. A withdrawn medicine is still found. Takes no query parameters. 503 `terms_unread` until a person has read EMA's terms.\n", "parameters": [ { "$ref": "#/components/parameters/EmaProductNumberPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmaMedicineResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/providers/nppes": { "get": { "tags": [ "health" ], "operationId": "searchNppesProviders", "summary": "Search the NPPES NPI Registry", "description": "Providers of the NPPES NPI Registry, one row per NPI, as the worker projected them (practice location, no mailing address, no phone numbers). These are records about named individuals, so this is a **search, not an enumeration**: give `npi` (up to 20, comma-separated), or `state` together with `last_name`, `organization_name` (a prefix of at least 3 characters) or `taxonomy`; anything less is 400. Ordered by NPI, at most 100 a page (default 25); there is no change feed and no bulk route. Names match case-insensitively, `state` and `taxonomy` exactly. `meta.status` is `not_loaded` until a monthly baseline has been applied and `degraded` while a gap in the weekly files is unrepaired; `meta.load` says what has been applied. 503 `terms_unread` until a person has read CMS's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "npi", "in": "query", "description": "One or more NPIs, comma-separated (at most 20), each exactly 10 digits.", "schema": { "type": "string" } }, { "name": "last_name", "in": "query", "description": "Legal last name, case-insensitive exact. Needs `state`.", "schema": { "type": "string" } }, { "name": "first_name", "in": "query", "description": "Legal first name, case-insensitive exact. Narrows `last_name`; not allowed without it.", "schema": { "type": "string" } }, { "name": "organization_name", "in": "query", "description": "Prefix of the legal business name, case-insensitive, at least 3 characters. Needs `state`.", "schema": { "type": "string", "minLength": 3 } }, { "name": "taxonomy", "in": "query", "description": "The 10-character NUCC taxonomy code of the primary taxonomy (case-insensitive). Needs `state`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{10}$" } }, { "name": "state", "in": "query", "description": "Two-letter practice-location state code (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "deactivated", "in": "query", "description": "`true`: only NPIs with a deactivation date; `false`: only those without. Narrows a search; it is not one by itself.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NppesProvidersResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/providers/nppes/{npi}": { "get": { "tags": [ "health" ], "operationId": "getNppesProvider", "summary": "One NPPES provider by NPI", "description": "Every stored column. Takes no query parameters. 404 for an NPI we do not hold (`meta.load` says what has been applied). 503 `terms_unread` until a person has read CMS's terms.\n", "parameters": [ { "$ref": "#/components/parameters/NppesNpiPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NppesProviderResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/trials/clinicaltrials_gov": { "get": { "tags": [ "health" ], "operationId": "listTrialsStudies", "summary": "ClinicalTrials.gov studies", "description": "Studies of the ClinicalTrials.gov registry as the worker projected them, one row per NCT id. Ordered by `(updated_at, nct_id)` ascending, so `updated_since` plus the cursor is a change feed. The three prose fields (`brief_summary`, `detailed_description`, `eligibility_criteria`) are left out unless `include=prose`, and the page is then capped at 100. List filters (`phase`, `condition`, `country`) match one element of the study's array exactly as published (case-sensitive). `meta.status` is `backfilling` until the first full read of the registry has completed. 503 `terms_unread` until a person has read the registry's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "overall_status", "in": "query", "description": "Exact, as published (e.g. RECRUITING, COMPLETED).", "schema": { "type": "string" } }, { "name": "study_type", "in": "query", "description": "Exact, as published (e.g. INTERVENTIONAL).", "schema": { "type": "string" } }, { "name": "phase", "in": "query", "description": "One phase as published (e.g. PHASE2); a study of two phases matches either.", "schema": { "type": "string" } }, { "name": "sponsor", "in": "query", "description": "Exact `lead_sponsor`, as published.", "schema": { "type": "string" } }, { "name": "condition", "in": "query", "description": "One element of `conditions`, exactly as published.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "One element of `location_countries`, exactly as published (e.g. France).", "schema": { "type": "string" } }, { "name": "has_results", "in": "query", "description": "Whether the registry holds results for the study.", "schema": { "type": "boolean" } }, { "name": "first_post_since", "in": "query", "description": "YYYY-MM-DD on `first_post_date` (inclusive).", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "name": "include", "in": "query", "description": "`prose` adds the three long text fields the list leaves out (page cap 100).", "schema": { "type": "string", "enum": [ "prose" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000, or 1-100 with `include=prose`.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialsStudiesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/trials/clinicaltrials_gov/{nct_id}": { "get": { "tags": [ "health" ], "operationId": "getTrialsStudy", "summary": "One ClinicalTrials.gov study, with its prose", "description": "Every column but the worker's own hash, the prose fields included. Takes no query parameters. 404 for a study we do not hold (the worker reads the registry in stages; `meta.walk` says how far). 503 `terms_unread` until a person has read the registry's terms.\n", "parameters": [ { "$ref": "#/components/parameters/TrialsNctIdPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialsStudyResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_510k_summary": { "get": { "tags": [ "health" ], "operationId": "listFdaSummaries", "summary": "FDA 510(k) summary documents (extracted text)", "description": "The text of 510(k) summary documents, one row per clearance, as the worker extracted it from the PDF. Only clearances whose document produced text are listed. Ordered by `(updated_at, k_number)` ascending; `updated_at` moves only when the text changes, so `updated_since` plus the cursor is a change feed. `k_number` matches the start of the number. `content` is left out unless `include=content`, and the page is then capped at 25 rows (a single summary can be two million characters). `meta.status` is `backfilling` while the first fill has clearances left; `meta.run` says how many. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "k_number", "in": "query", "description": "A prefix of the clearance number: 1-9 letters or digits, upper-cased (`K23`, `DEN25`).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{1,9}$" } }, { "name": "decision_date_from", "in": "query", "description": "YYYY-MM-DD, inclusive, on the FDA decision date.", "schema": { "type": "string", "format": "date" } }, { "name": "decision_date_to", "in": "query", "description": "YYYY-MM-DD, inclusive. Not before `decision_date_from`.", "schema": { "type": "string", "format": "date" } }, { "name": "product_code", "in": "query", "description": "Exact FDA product code, upper-cased.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "name": "include", "in": "query", "description": "`content` adds the extracted text (page cap 25).", "schema": { "type": "string", "enum": [ "content" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000, or 1-25 with `include=content` (the default then is 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaSummariesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_510k_summary/{k_number}": { "get": { "tags": [ "health" ], "operationId": "getFdaSummary", "summary": "One 510(k) summary, with its text", "description": "The row with its `content`. Takes no query parameters. 404 for a clearance with no extracted text (the document has not been read yet, is not on the publisher's site, or has no text layer): the other states are the worker's bookkeeping and are not served. 400 for a number that is not letters then six digits. 503 `terms_unread` until a person has read the publisher's terms.\n", "parameters": [ { "$ref": "#/components/parameters/FdaSummaryKNumberPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_label": { "get": { "tags": [ "health" ], "operationId": "listFdaLabel", "summary": "openFDA drug labels (prescribing information)", "description": "Records of the openFDA endpoint `drug/label` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_label/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaLabel", "summary": "One record of: openFDA drug labels (prescribing information)", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_ndc": { "get": { "tags": [ "health" ], "operationId": "listFdaNdc", "summary": "openFDA National Drug Code directory", "description": "Records of the openFDA endpoint `drug/ndc` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_ndc/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaNdc", "summary": "One record of: openFDA National Drug Code directory", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_drugsfda": { "get": { "tags": [ "health" ], "operationId": "listFdaDrugsfda", "summary": "openFDA Drugs@FDA approvals", "description": "Records of the openFDA endpoint `drug/drugsfda` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_drugsfda/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaDrugsfda", "summary": "One record of: openFDA Drugs@FDA approvals", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_orangebook": { "get": { "tags": [ "health" ], "operationId": "listFdaOrangebook", "summary": "openFDA Orange Book", "description": "Records of the openFDA endpoint `drug/orangebook` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_orangebook/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaOrangebook", "summary": "One record of: openFDA Orange Book", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_shortages": { "get": { "tags": [ "health" ], "operationId": "listFdaShortages", "summary": "openFDA drug shortages", "description": "Records of the openFDA endpoint `drug/shortages` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_shortages/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaShortages", "summary": "One record of: openFDA drug shortages", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_nsde": { "get": { "tags": [ "health" ], "operationId": "listFdaNsde", "summary": "openFDA NDC SPL data elements (NSDE)", "description": "Records of the openFDA endpoint `other/nsde` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_nsde/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaNsde", "summary": "One record of: openFDA NDC SPL data elements (NSDE)", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_unii": { "get": { "tags": [ "health" ], "operationId": "listFdaUnii", "summary": "openFDA UNII substance identifiers", "description": "Records of the openFDA endpoint `other/unii` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_unii/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaUnii", "summary": "One record of: openFDA UNII substance identifiers", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_substance": { "get": { "tags": [ "health" ], "operationId": "listFdaSubstance", "summary": "openFDA substance data", "description": "Records of the openFDA endpoint `other/substance` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_substance/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaSubstance", "summary": "One record of: openFDA substance data", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_historicaldocument": { "get": { "tags": [ "health" ], "operationId": "listFdaHistoricaldocument", "summary": "openFDA historical documents", "description": "Records of the openFDA endpoint `other/historicaldocument` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_historicaldocument/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaHistoricaldocument", "summary": "One record of: openFDA historical documents", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_enforcement": { "get": { "tags": [ "health" ], "operationId": "listFdaEnforcement", "summary": "openFDA drug enforcement reports (recalls)", "description": "Records of the openFDA endpoint `drug/enforcement` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_enforcement/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaEnforcement", "summary": "One record of: openFDA drug enforcement reports (recalls)", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_crl": { "get": { "tags": [ "health" ], "operationId": "listFdaCrl", "summary": "openFDA complete response letters", "description": "Records of the openFDA endpoint `transparency/crl` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/drugs/fda_crl/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaCrl", "summary": "One record of: openFDA complete response letters", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_510k": { "get": { "tags": [ "health" ], "operationId": "listFda510k", "summary": "openFDA 510(k) clearances", "description": "Records of the openFDA endpoint `device/510k` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_510k/{key}": { "get": { "tags": [ "health" ], "operationId": "getFda510k", "summary": "One record of: openFDA 510(k) clearances", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_pma": { "get": { "tags": [ "health" ], "operationId": "listFdaPma", "summary": "openFDA premarket approvals (PMA)", "description": "Records of the openFDA endpoint `device/pma` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_pma/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaPma", "summary": "One record of: openFDA premarket approvals (PMA)", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one, such as `P140004/S092` or `P140004/`) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_classification": { "get": { "tags": [ "health" ], "operationId": "listFdaClassification", "summary": "openFDA device classification", "description": "Records of the openFDA endpoint `device/classification` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_classification/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaClassification", "summary": "One record of: openFDA device classification", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_udi": { "get": { "tags": [ "health" ], "operationId": "listFdaUdi", "summary": "openFDA unique device identifiers (UDI)", "description": "Records of the openFDA endpoint `device/udi` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_udi/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaUdi", "summary": "One record of: openFDA unique device identifiers (UDI)", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_registrationlisting": { "get": { "tags": [ "health" ], "operationId": "listFdaRegistrationlisting", "summary": "openFDA device registration and listing", "description": "Records of the openFDA endpoint `device/registrationlisting` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_registrationlisting/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaRegistrationlisting", "summary": "One record of: openFDA device registration and listing", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_covid19serology": { "get": { "tags": [ "health" ], "operationId": "listFdaCovid19serology", "summary": "openFDA COVID-19 serology tests", "description": "Records of the openFDA endpoint `device/covid19serology` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_covid19serology/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaCovid19serology", "summary": "One record of: openFDA COVID-19 serology tests", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_recall": { "get": { "tags": [ "health" ], "operationId": "listFdaRecall", "summary": "openFDA device recalls", "description": "Records of the openFDA endpoint `device/recall` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_recall/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaRecall", "summary": "One record of: openFDA device recalls", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_device_enforcement": { "get": { "tags": [ "health" ], "operationId": "listFdaDeviceEnforcement", "summary": "openFDA device enforcement reports", "description": "Records of the openFDA endpoint `device/enforcement` as the worker stored them, whole, as `payload` (nothing renamed or flattened). Ordered by `(updated_at, key)` ascending; `updated_at` moves only when the record's content changed, so `updated_since` plus the cursor is a change feed. `key_prefix` matches the start of the key. There are no per-field filters. A page is cut to a stored-size budget (4 MiB of payload): it can be shorter than `limit` and still have a `next_cursor`, which is normal. `meta` says which export the rows come from and how many partitions of the endpoint are imported, pending or failed; `meta.status` is `backfilling` while partitions are pending and `degraded` when some are stuck. 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "name": "key_prefix", "in": "query", "description": "The key starts with this text (case-sensitive; `%`, `_` and `\\` are literal). A composite key is `part1/part2`: `P140004/` is that PMA's original application and all its supplements.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000 (a page can be shorter, see above).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/devices/fda_device_enforcement/{key}": { "get": { "tags": [ "health" ], "operationId": "getFdaDeviceEnforcement", "summary": "One record of: openFDA device enforcement reports", "description": "One record by its `key` exactly as listed. A key with a `/` (a composite one) may be sent raw or with `%2F`. Found whether or not the latest export held it (`in_latest_export`). Takes no query parameters. 404 for a record we do not hold (the worker imports the export in stages; `meta.partitions` says how far). 503 `terms_unread` until a person has read the publisher's terms. [the health guide](https://docs.aggre.org/datasets/health).\n", "parameters": [ { "$ref": "#/components/parameters/FdaKeyPath" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdaRecordResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/who_gho": { "get": { "tags": [ "health" ], "operationId": "listWhoObservations", "summary": "WHO Global Health Observatory observations of one indicator", "description": "Observations of one curated indicator (the whole table is far too large to page as one), ordered by `(spatial_dim, year, breakdown_key)` within one `spatial_dim_type` (default `COUNTRY`; regions and the world are other types). Rows the indicator's last complete read no longer contained are returned with `in_latest_read: false`. `value_display` is WHO's own formatted string. 404 `not_found` for an indicator not in the catalogue; 503 `terms_unread` until a person has read WHO's terms.\n", "parameters": [ { "name": "indicator", "in": "query", "required": true, "description": "Our indicator id (`life_expectancy`) or its GHO code (`WHOSIS_000001`); see the catalogue.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, { "name": "spatial_dim_type", "in": "query", "description": "COUNTRY (default), GLOBAL, REGION, UNSDGREGION, … as published.", "schema": { "type": "string", "default": "COUNTRY", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, { "name": "spatial_dim", "in": "query", "description": "One place code as published (an ISO country code for COUNTRY).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, { "name": "breakdown", "in": "query", "description": "Dimension filter, `TYPE:value` pairs separated by commas, at most three, e.g. `SEX:SEX_MLE`. A row matches when its `breakdown` contains every pair.", "schema": { "type": "string" } }, { "name": "year_from", "in": "query", "description": "First year, 1900-2100.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "year_to", "in": "query", "description": "Last year, 1900-2100.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoObservationsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/who_gho/indicators": { "get": { "tags": [ "health" ], "operationId": "listWhoIndicators", "summary": "The curated WHO GHO indicators", "description": "The catalogue: id, GHO code, category, Aggre's own description, whether the indicator is read page by page, and when its last complete read ended and how many rows it held. Takes no query parameters. 503 `terms_unread` until a person has read WHO's terms.\n", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoIndicatorsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/eurostat_mortality": { "get": { "tags": [ "health" ], "operationId": "listEurostatMortality", "summary": "Eurostat causes of death, cells of one cause", "description": "Cells of one cause code (`icd10` is required: without it the list would be a dump of ~600k cells), ordered by `(updated_at, year, geo)`, so `updated_since` plus the cursor is a change feed. A cell the last complete read of its year no longer held has `in_latest_read: false`. `value` is null for a status-only cell. `meta.years` carries the dataset's own `updated` text per year read. 503 `terms_unread` until a person has read Eurostat's terms.\n", "parameters": [ { "name": "icd10", "in": "query", "required": true, "description": "One cause code as published (`C33_C34`, `A-R_V-Y`, …); the causes route lists them.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" } }, { "name": "geo", "in": "query", "description": "Exact Eurostat place codes, comma-separated, at most 20 (`DE,DE21,EU27_2020`).", "schema": { "type": "string" } }, { "name": "geo_kind", "in": "query", "description": "Our derived kind of place: country (two letters), nuts2 (two letters plus two characters), aggregate (EU…, EA…, EFTA…) or other. Derived by Aggre from the code's shape, not by Eurostat.", "schema": { "type": "string", "enum": [ "country", "nuts2", "aggregate", "other" ] } }, { "name": "year", "in": "query", "description": "One year; cannot be combined with year_from or year_to.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "year_from", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "year_to", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "status", "in": "query", "description": "Eurostat's flag, exactly as published.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,32}$" } }, { "name": "has_value", "in": "query", "description": "`true`: only cells with a value; `false`: only status-only cells.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/HealthUpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "description": "Rows per page: 1-1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EurostatMortalityResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/eurostat_mortality/causes": { "get": { "tags": [ "health" ], "operationId": "listEurostatCauses", "summary": "Cause codes in the Eurostat table", "description": "The cause codes present in the table with their labels, derived from the table. Takes no query parameters. 503 `terms_unread` until a person has read Eurostat's terms.\n", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EurostatCausesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/eurostat_mortality/places": { "get": { "tags": [ "health" ], "operationId": "listEurostatPlaces", "summary": "Place codes in the Eurostat table", "description": "The place codes present in the table with their labels and our derived `geo_kind`. 503 `terms_unread` until a person has read Eurostat's terms.\n", "parameters": [ { "name": "geo_kind", "in": "query", "description": "Our derived kind of place: country (two letters), nuts2 (two letters plus two characters), aggregate (EU…, EA…, EFTA…) or other. Derived by Aggre from the code's shape, not by Eurostat.", "schema": { "type": "string", "enum": [ "country", "nuts2", "aggregate", "other" ] } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EurostatPlacesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/health/statistics/eurostat_mortality/{year}/{geo}/{icd10}": { "get": { "tags": [ "health" ], "operationId": "getEurostatMortality", "summary": "One Eurostat cell", "description": "The cell of one year, place and cause. Takes no query parameters. 503 `terms_unread` until a person has read Eurostat's terms.\n", "parameters": [ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "geo", "in": "path", "required": true, "description": "Eurostat place code.", "schema": { "type": "string" } }, { "name": "icd10", "in": "path", "required": true, "description": "Cause code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EurostatCellResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Error" } } } } } }