{"openapi":"3.0.3","info":{"title":"Macro Data API","description":"Macro and economic data for AI agents: CPI, payrolls, GDP, PCE, policy rates, yield curves and release calendars from the primary statistical agencies, with point-in-time vintages. Pay per request in USDC over x402, or use an API key.","version":"2026.11.02"},"paths":{"/api/v1/health":{"get":{"tags":["Meta"],"summary":"Health (no key)","operationId":"health_api_v1_health_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"tags":["Meta"],"summary":"Health (no key)","operationId":"health_api_v1_health_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/health/data":{"get":{"tags":["Meta"],"summary":"Collection health (no key)","operationId":"health_data_api_v1_health_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/pricing":{"get":{"tags":["Meta"],"summary":"Agent pricing (no key)","description":"Every way to pay over x402 with exact USDC prices. This is also the pricing document RealtimeAPI imports.","operationId":"pricing_api_v1_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/auth/keys":{"post":{"tags":["Authentication"],"summary":"Create a free API key (no signup)","description":"Returns an `mdk_live_` key once. Free tier: 10 requests a minute, 500 a day.","operationId":"create_key_api_v1_auth_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Authentication"],"summary":"Revoke your key","operationId":"revoke_api_v1_auth_keys_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/auth/keys/me":{"get":{"tags":["Authentication"],"summary":"Your key's tier and usage","operationId":"key_me_api_v1_auth_keys_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/auth/keys/rotate":{"post":{"tags":["Authentication"],"summary":"Rotate your key","operationId":"rotate_api_v1_auth_keys_rotate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/series":{"get":{"tags":["Series"],"summary":"Series catalog","description":"Every series we collect with publisher, unit, frequency, latest period and next scheduled release. Filter by publisher, country or category. Refreshes every 60 minutes.","operationId":"list_series_api_v1_series_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"publisher","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Publisher","examples":["BLS"]}},{"name":"country","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Country","examples":["US"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Category","examples":["inflation"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Q","examples":["cpi"]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"series_list","x-cadence":"Refreshes every 60 minutes."}},"/api/v1/series/{series_id}":{"get":{"tags":["Series"],"summary":"Latest value of a series","description":"The latest print with the previous period, period-over-period and year-over-year change, when it was released and when the next release is scheduled. Refreshes at each release; polled every 5 minutes on release days.","operationId":"series_latest_api_v1_series__series_id__get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"series_id","in":"path","required":true,"schema":{"type":"string","title":"Series Id"},"example":"us.cpi.all.sa"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"series_latest","x-cadence":"Refreshes at each release; polled every 5 minutes on release days."}},"/api/v1/series/{series_id}/history":{"get":{"tags":["Series"],"summary":"History of a series (point-in-time with as_of)","description":"Observations newest first. With `as_of`, every period is returned as it was known on that date (the newest vintage on or before it), which is what a backtest needs. Refreshes at each release.","operationId":"series_history_api_v1_series__series_id__history_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"series_id","in":"path","required":true,"schema":{"type":"string","title":"Series Id"},"example":"us.cpi.all.sa"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":120,"title":"Limit"}},{"name":"as_of","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"title":"As Of","examples":["2026-06-30"]}},{"name":"start","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Start","description":"Earliest period to include, e.g. 2020-01 or 2020-Q1"},"description":"Earliest period to include, e.g. 2020-01 or 2020-Q1"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.02","x-price":{"price_micro":20000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"series_history","x-cadence":"Refreshes at each release."}},"/api/v1/series/{series_id}/vintages":{"get":{"tags":["Series"],"summary":"Revisions of one period","description":"Every value we have recorded for one period of one series, oldest vintage first: the initial print and each revision with its vintage date. Refreshes at each release.","operationId":"series_vintages_api_v1_series__series_id__vintages_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"series_id","in":"path","required":true,"schema":{"type":"string","title":"Series Id"},"example":"us.cpi.all.sa"},{"name":"period","in":"query","required":true,"schema":{"type":"string","example":"2026-09","title":"Period"},"example":"2026-09"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.02","x-price":{"price_micro":20000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"series_vintages","x-cadence":"Refreshes at each release."}},"/api/v1/releases/upcoming":{"get":{"tags":["Releases"],"summary":"Upcoming data releases","description":"Scheduled releases for the next `days` days across every publisher, with the series each one updates. Refreshes every 5 minutes.","operationId":"releases_upcoming_api_v1_releases_upcoming_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"default":7,"title":"Days"}},{"name":"publisher","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Publisher","examples":["BLS"]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"releases_upcoming","x-cadence":"Refreshes every 5 minutes."}},"/api/v1/releases/latest":{"get":{"tags":["Releases"],"summary":"Latest observed releases","description":"The most recent releases we observed, newest first, with the headline series that changed. Refreshes every 60 seconds.","operationId":"releases_latest_api_v1_releases_latest_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}},{"name":"publisher","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Publisher"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"releases_latest","x-cadence":"Refreshes every 60 seconds."}},"/api/v1/rates/policy":{"get":{"tags":["Releases"],"summary":"Central bank policy rates","description":"Current policy rate for the Fed (target range), ECB (deposit facility), Bank of England (Bank Rate) and RBA (cash rate target), with the last decision date and the next scheduled meeting. Refreshes every 5 minutes.","operationId":"policy_rates_api_v1_rates_policy_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"bank","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Bank","examples":["fed"]}},{"name":"history","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"default":0,"title":"History"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"rates_policy","x-cadence":"Refreshes every 5 minutes."}},"/api/v1/yields/{country}":{"get":{"tags":["Yields"],"summary":"Daily par yield curve","description":"Every tenor of the par yield curve for the latest session (or the session on or before `date`), the previous session, the change per tenor and the 2s10s and 3m10y spreads. US today. Refreshes every 30 minutes.","operationId":"yield_curve_api_v1_yields__country__get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","title":"Country"},"example":"us"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"title":"Date","examples":["2026-10-30"]}},{"name":"history","in":"query","required":false,"schema":{"type":"integer","maximum":250,"minimum":0,"description":"Also return the last N sessions","default":0,"title":"History"},"description":"Also return the last N sessions"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"yields_country","x-cadence":"Refreshes every 30 minutes."}},"/api/v1/payments/plans":{"get":{"tags":["Payments"],"summary":"Passes and accepted networks (no key)","operationId":"get_plans_api_v1_payments_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/payments/agent-subscribe":{"post":{"tags":["Payments"],"summary":"Buy a pass (x402, gasless USDC)","description":"Two calls: first without a payment header returns 402 with the USDC amount and\nnetworks; the second with the signed `x-payment` header settles and returns an\n`mdk_live_` key (shown once) with a Pro pass. Passes stack: buying while one is active extends it.\n\nSend `X-API-Key` to extend an existing key instead of minting one.","operationId":"agent_subscribe_api_v1_payments_agent_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSubscribeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/payments/invoices":{"get":{"tags":["Payments"],"summary":"Invoices for the calling key","operationId":"list_invoices_api_v1_payments_invoices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"APIKeyCreate":{"properties":{"email":{"type":"string","title":"Email","description":"Where this key belongs. Agents: your human's real address, else your own mailbox.","example":"owner@yourcompany.com"}},"type":"object","required":["email"],"title":"APIKeyCreate"},"AgentSubscribeRequest":{"properties":{"plan":{"type":"string","title":"Plan","description":"pass_1h, pass_1d or pass_7d","example":"pass_1d"}},"type":"object","required":["plan"],"title":"AgentSubscribeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://macrodataapi.com"}],"tags":[{"name":"Meta","description":"Health, index and pricing. No key."},{"name":"Authentication","description":"Free keys and key management."},{"name":"Series","description":"Catalog, latest values, point-in-time history and vintages."},{"name":"Releases","description":"Release calendar, observed releases and policy rates."},{"name":"Yields","description":"Daily par yield curves."},{"name":"Payments","description":"x402 timed passes and invoices. No subscriptions."}]}