{ "openapi": "3.1.0", "info": { "title": "Foresight API", "version": "1.0.0", "description": "OpenAPI document for the live v1 read API surface in this tree. Catalog routes and signup are anonymous; observations, insights, signals, and ping require bearer API keys (or x402 payment on payable endpoints).", "termsOfService": "https://api.creativeforesight.io/terms", "contact": { "name": "Creative Foresight", "url": "https://creativeforesight.io", "email": "support@creativeforesight.io" }, "x-guidance": "The Foresight API serves economic, demographic, financial, and Creative Foresight original (cf:*) time-series as clean JSON. Start with the free catalog routes (/v1/sources, /v1/regions, /v1/indicators) to find indicator and region codes, then read data with /v1/observations, /v1/observations/latest, /v1/insights, /v1/panel, /v1/flows, /v1/signals, and /v1/ask (natural-language questions). Paid routes accept either a bearer API key (create a free key via POST /v1/signup) or an anonymous x402 v2 payment: retry the 402 challenge with a signed PAYMENT-SIGNATURE header (USDC on Base). Data reads cost $0.01-$0.05 per request; /v1/ask costs $0.25 ($1.50 at briefing depth). Full docs: https://docs.creativeforesight.io." }, "servers": [ { "url": "https://api.creativeforesight.io", "description": "Production" } ], "security": [], "tags": [ { "name": "Catalog", "description": "Free, unauthenticated discovery of what the API covers: the data-source registry, the region hierarchy, and the indicator catalog with per-indicator detail (available regions and date range). Start here to resolve the indicator and region codes every priced read endpoint takes." }, { "name": "Signup", "description": "Self-serve creation of a free-tier live API key. Public and rate-limited per hashed client IP; the raw key is returned once, at creation, and cannot be retrieved again." }, { "name": "Keys", "description": "Self-serve key management: rotate or revoke a key with the key itself, or recover a paid key through a single-use token emailed to its billing address. Rotation keeps the same plan, limits, usage, and billing. A rotated free key comes back in the response; a paid key's replacement is only ever emailed." }, { "name": "Observations", "description": "Time-series reads over the indicator catalog: full observation history for one indicator, the latest value for one indicator or a batch of up to 20, and aligned multi-indicator panels sharing a single date grid. Payable per request with a bearer key or x402." }, { "name": "Flows", "description": "Directed origin-to-destination flow rows between regions for a given measure and period. When no period is requested the latest available one is used and reported in the response meta." }, { "name": "Insights", "description": "Interpretation layered over the series rather than the raw numbers: deterministic computed facts plus active signals for one indicator, natural-language questions answered with a citation trace, the curated public briefing catalog, and per-key saved briefings that re-run an ask question on a schedule." }, { "name": "Signals", "description": "Premium detected signals — acceleration, extreme, and trend-break — served either as the intervals currently active or as the full interval history, filterable by indicator, region, type, and strength." }, { "name": "Diagnostics", "description": "Credential and connectivity checks that touch no data. Ping validates a bearer API key and echoes back the key name." } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cf_live_ or cf_test_ API key", "description": "Foresight API key sent as an Authorization: Bearer header." } }, "headers": { "X-Request-Id": { "description": "Request correlation identifier. Stamped on every response of a gated operation, on both the bearer-key rail (src/lib/apiKeyAuth.ts) and the anonymous x402/L402 rails (src/lib/x402.ts).", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "Configured request limit for the current one-minute window. Sent on bearer API key requests only; anonymous x402/L402 requests are not key-rate-limited and omit it.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in the current one-minute window. Sent on bearer API key requests only; anonymous x402/L402 requests are not key-rate-limited and omit it.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the current one-minute window resets. Sent on bearer API key requests only; anonymous x402/L402 requests are not key-rate-limited and omit it.", "schema": { "type": "integer" } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY", "EXPIRED_API_KEY", "RATE_LIMIT_EXCEEDED", "UPGRADE_REQUIRED", "INVALID_REQUEST", "INVALID_PARAMETER", "RESOURCE_NOT_FOUND", "CATEGORY_NOT_ALLOWED", "REGION_NOT_ALLOWED", "ASK_UNAVAILABLE", "SUBSCRIPTION_ACTIVE", "INTERNAL_ERROR", "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false }, "Source": { "type": "object", "required": [ "slug", "name", "provider", "category", "indicator_count", "docs_url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "indicator_count": { "type": "integer", "minimum": 0 }, "docs_url": { "type": [ "string", "null" ], "format": "uri" } }, "additionalProperties": false }, "Indicator": { "type": "object", "required": [ "id", "code", "name", "description", "source", "category", "subcategory", "access_tier", "unit", "frequency", "is_active" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] }, "access_tier": { "type": "string", "enum": [ "free", "premium" ], "description": "premium requires an API key granting creative-foresight, or x402" }, "unit": { "type": [ "string", "null" ] }, "frequency": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "display": { "type": "object", "description": "Optional display metadata copied from indicator extra.display.", "additionalProperties": true }, "projection": { "type": "boolean", "const": true, "description": "Present on projection series (e.g. CBO potential GDP, GDPPOT): periods after the latest publication are forecasts. /v1/observations/latest returns the latest non-future period." } }, "additionalProperties": false }, "IndicatorDetail": { "type": "object", "required": [ "id", "code", "name", "description", "source", "category", "subcategory", "access_tier", "unit", "frequency", "default_region", "available_regions", "date_range" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source": { "oneOf": [ { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "category": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] }, "access_tier": { "type": "string", "enum": [ "free", "premium" ], "description": "premium requires an API key granting creative-foresight, or x402" }, "unit": { "type": [ "string", "null" ] }, "frequency": { "type": [ "string", "null" ] }, "default_region": { "oneOf": [ { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "available_regions": { "type": "array", "items": { "type": "string" } }, "date_range": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": [ "string", "null" ], "format": "date" }, "end": { "type": [ "string", "null" ], "format": "date" } }, "additionalProperties": false }, "projection": { "type": "boolean", "const": true, "description": "Present on projection series: date_range.end is a forecast period." }, "retired": { "type": "object", "description": "Present when the series has been retired from the catalog (orphaned, superseded, discontinued upstream or never ingested). Its stored data is still served; it no longer updates.", "required": [ "retired_at", "reason" ], "properties": { "retired_at": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "replaced_by": { "type": "string", "description": "The indicator code that replaces this series, when there is one." } }, "additionalProperties": false } }, "additionalProperties": false }, "Region": { "type": "object", "required": [ "code", "type", "name", "slug", "parent_code", "fips_state", "fips_county" ], "properties": { "code": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_code": { "type": [ "string", "null" ] }, "fips_state": { "type": [ "string", "null" ] }, "fips_county": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "Flow": { "type": "object", "required": [ "origin", "destination", "measure", "period_start", "value" ], "properties": { "origin": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "destination": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "measure": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "value": { "type": "number" } }, "additionalProperties": false }, "FlowsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Flow" } }, "meta": { "type": "object", "required": [ "count", "limit", "period", "filters", "units" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0, "maximum": 500 }, "period": { "type": [ "string", "null" ], "format": "date" }, "filters": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "measure": { "type": "string" } }, "additionalProperties": false }, "units": { "type": "object", "required": [ "agi", "returns", "individuals" ], "properties": { "agi": { "type": "string", "const": "USD, thousands" }, "returns": { "type": "string", "const": "count" }, "individuals": { "type": "string", "const": "count" } }, "additionalProperties": false }, "source_attribution": { "type": "string", "description": "Attribution text for the data source behind the returned rows. Omitted when no rows match or the source records none." } }, "additionalProperties": false } }, "additionalProperties": false }, "Observation": { "type": "object", "required": [ "period_start", "period_end", "period_type", "value", "revision", "is_preliminary", "source_updated_at" ], "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "period_type": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "revision": { "type": "integer" }, "is_preliminary": { "type": "boolean" }, "source_updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "LatestObservation": { "type": "object", "required": [ "indicator", "region", "period_start", "period_end", "period_type", "value", "revision", "is_preliminary", "source_updated_at", "unit" ], "properties": { "indicator": { "type": "string" }, "region": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "period_type": { "type": [ "string", "null" ] }, "value": { "type": "number" }, "revision": { "type": "integer" }, "is_preliminary": { "type": "boolean" }, "source_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "unit": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PanelResponse": { "type": "object", "required": [ "dates", "series", "meta" ], "properties": { "dates": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "Single aligned date grid shared by every returned series." }, "series": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": [ "number", "null" ] } }, "description": "Indicator-code keyed arrays aligned positionally to dates." }, "meta": { "type": "object", "required": [ "units", "alignment", "region", "frequency" ], "description": "Panel metadata. Per-series nature metadata is intentionally omitted in panel v1.", "properties": { "units": { "type": "object", "additionalProperties": { "type": "string" } }, "alignment": { "type": "object", "required": [ "missing", "grid_points" ], "properties": { "missing": { "type": "string", "enum": [ "drop", "ffill" ] }, "grid_points": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Aligned date count before multiplying by series count." } }, "additionalProperties": false }, "region": { "type": [ "string", "null" ] }, "frequency": { "type": "string", "enum": [ "daily", "monthly", "quarterly", "annual" ] }, "resample": { "type": "object", "required": [ "method", "sources" ], "properties": { "method": { "type": "string", "enum": [ "mean", "last", "sum" ] }, "sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "annual" ] }, "description": "Indicator-code keyed native frequencies for series resampled to the panel target." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "Provisioning": { "type": "object", "required": [ "status", "indicator", "region", "retry_after_seconds", "request_ref" ], "properties": { "status": { "type": "string", "const": "provisioning" }, "indicator": { "type": "string" }, "region": { "type": "string" }, "retry_after_seconds": { "type": "integer", "minimum": 1 }, "request_ref": { "type": "string" } }, "additionalProperties": false }, "InsightFact": { "type": "object", "required": [ "kind", "params", "humanTemplate", "salience", "text" ], "properties": { "kind": { "type": "string", "enum": [ "trend", "latest_delta", "watermark_high_distance", "watermark_low_distance", "longest_run", "peer_rank" ] }, "params": { "type": "object", "additionalProperties": true }, "humanTemplate": { "type": "string" }, "salience": { "type": "number", "minimum": 0, "maximum": 1 }, "text": { "type": [ "string", "null" ], "description": "Shareable, plain-spoken sentence rendered from the fact + curated display metadata (ADR-0008). Null when the indicator is not yet curated." } }, "additionalProperties": false }, "InsightSignal": { "type": "object", "required": [ "id", "indicator", "region", "kind", "strength", "direction", "salience", "summary", "observed_at", "vocabulary", "text" ], "properties": { "id": { "type": "string" }, "indicator": { "type": "string" }, "region": { "type": "string" }, "kind": { "type": "string" }, "strength": { "type": "string", "enum": [ "weak", "neutral", "strong" ] }, "direction": { "type": [ "string", "null" ] }, "salience": { "type": "number", "minimum": 0, "maximum": 1 }, "summary": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "evidence": { "type": "object", "additionalProperties": true }, "vocabulary": { "type": "object", "required": [ "glyph", "label", "tone" ], "properties": { "glyph": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "positive", "negative", "neutral" ] } }, "additionalProperties": false }, "text": { "type": [ "string", "null" ], "description": "Shareable, plain-spoken sentence for the signal (ADR-0008). Null when uncurated." } }, "additionalProperties": false }, "Signal": { "type": "object", "required": [ "id", "indicator", "region", "type", "strength", "direction", "valid_from", "valid_to", "detected_at", "last_seen_at", "evidence", "vocabulary", "text" ], "properties": { "id": { "type": "string", "format": "uuid" }, "indicator": { "type": "object", "required": [ "code", "name", "category", "unit", "frequency", "source" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "frequency": { "type": [ "string", "null" ] }, "source": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "region": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "type": { "type": "string", "enum": [ "acceleration", "extreme", "trend_break" ] }, "strength": { "type": "string", "enum": [ "weak", "neutral", "strong" ] }, "direction": { "type": [ "string", "null" ] }, "valid_from": { "type": "string", "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" }, "detected_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "evidence": { "type": "object", "additionalProperties": true }, "vocabulary": { "type": "object", "required": [ "glyph", "label", "tone" ], "properties": { "glyph": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "positive", "negative", "neutral" ] } }, "additionalProperties": false }, "text": { "type": [ "string", "null" ], "description": "Shareable, plain-spoken sentence for the signal (ADR-0008). Null when uncurated." } }, "additionalProperties": false }, "Briefing": { "type": "object", "required": [ "id", "api_key_id", "name", "question", "region", "window", "cadence", "is_active", "is_public", "slug", "last_run_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": [ "string", "null" ] }, "window": { "type": [ "string", "null" ], "pattern": "^(all|[1-9][0-9]*[dmy])$" }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ] }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "slug": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "BriefingDetail": { "type": "object", "required": [ "id", "api_key_id", "name", "question", "region", "window", "cadence", "is_active", "is_public", "slug", "last_run_at", "created_at", "updated_at", "latest_run" ], "properties": { "id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": [ "string", "null" ] }, "window": { "type": [ "string", "null" ], "pattern": "^(all|[1-9][0-9]*[dmy])$" }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ] }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "slug": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "latest_run": { "oneOf": [ { "type": "object", "required": [ "result", "status", "started_at" ], "properties": { "result": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "running", "success", "no_data", "unavailable", "error" ] }, "started_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "BriefingRun": { "type": "object", "required": [ "id", "briefing_id", "started_at", "completed_at", "status", "result", "error", "usage" ], "properties": { "id": { "type": "string", "format": "uuid" }, "briefing_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "running", "success", "no_data", "unavailable", "error" ] }, "result": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "usage": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "additionalProperties": false }, "PublicBriefingSummary": { "type": "object", "required": [ "slug", "name", "question", "cadence", "last_run_at" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "PublicBriefingRead": { "type": "object", "required": [ "slug", "name", "question", "cadence", "run" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ] }, "run": { "type": "object", "required": [ "started_at", "completed_at", "result" ], "properties": { "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "result": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "responses": { "Unauthorized": { "description": "The request did not include a valid bearer API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "The API key exceeded its one-minute request limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InvalidParameter": { "description": "A query parameter was missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InvalidParameterKeyGated": { "description": "A query parameter was missing or invalid.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "QuotaExceeded": { "description": "The API key exhausted its free-tier monthly request quota (error.code UPGRADE_REQUIRED). The quota resets at the start of the next UTC month; upgrade to a paid Foresight API plan to continue before then.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PaymentRequired": { "description": "Payment Required. Anonymous requests receive an x402 v2 challenge: a JSON envelope, the base64-encoded PAYMENT-REQUIRED header, and a WWW-Authenticate Payment challenge. Retry with a signed PAYMENT-SIGNATURE header (USDC on Base) or use a bearer API key instead.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "ProvisioningStarted": { "description": "Just-in-time provisioning started for a resolvable miss (D15). Retry the identical request after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying the provisioning request.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provisioning" } } } } } }, "paths": { "/v1/sources": { "get": { "tags": [ "Catalog" ], "operationId": "listSources", "summary": "List data sources", "security": [], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Sources catalog.", "headers": { "Cache-Control": { "description": "Public CDN cache policy.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } }, "additionalProperties": false } } } }, "500": { "description": "The sources catalog could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/regions": { "get": { "tags": [ "Catalog" ], "operationId": "listRegions", "summary": "List regions", "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "parent", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Regions catalog.", "headers": { "Cache-Control": { "description": "Public CDN cache policy.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } }, "additionalProperties": false } } } }, "500": { "description": "The regions catalog could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/indicators": { "get": { "tags": [ "Catalog" ], "operationId": "listIndicators", "summary": "List indicators", "security": [], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Plain-words search (\"federal funds rate\", \"inflation\", \"oil price\"). Every term must match an indicator's name, code or description, with common economic synonyms expanded; results are ordered by relevance, headline national series first." }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "codes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated indicator codes." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Indicator catalog.", "headers": { "Cache-Control": { "description": "Public CDN cache policy.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Indicator" } }, "meta": { "type": "object", "required": [ "total", "limit", "offset" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "500": { "description": "The indicator catalog could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/indicators/{code}": { "get": { "tags": [ "Catalog" ], "operationId": "getIndicator", "summary": "Get indicator detail", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Indicator detail with available regions and date range.", "headers": { "Cache-Control": { "description": "Public CDN cache policy.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IndicatorDetail" }, "meta": { "type": "object", "required": [ "ambiguous_with" ], "properties": { "ambiguous_with": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "404": { "description": "The requested indicator was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Indicator detail or availability could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/signup": { "post": { "tags": [ "Signup" ], "operationId": "createApiKey", "summary": "Create a free-tier API key", "description": "Issues a self-serve live API key for free-tier access. Signup is public and rate-limited per hashed client IP.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Email address to label the self-serve free-tier API key." }, "source": { "type": "string", "maxLength": 120, "description": "Optional. Where did you find us? Free text, trimmed. Used only for anonymous attribution analytics; never stored with the key." }, "utm_source": { "type": "string", "maxLength": 120, "description": "Optional UTM source tag from the link that referred you." }, "utm_medium": { "type": "string", "maxLength": 120, "description": "Optional UTM medium tag from the link that referred you." }, "utm_campaign": { "type": "string", "maxLength": 120, "description": "Optional UTM campaign tag from the link that referred you." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "A free-tier live API key was created. Store the raw key immediately.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "key", "key_hint", "rate_limit_per_minute", "docs_url" ], "properties": { "key": { "type": "string", "pattern": "^cf_live_[0-9a-f]{64}$", "description": "Raw API key. It is shown once and cannot be retrieved later." }, "key_hint": { "type": "string", "maxLength": 8 }, "rate_limit_per_minute": { "type": "integer", "const": 60 }, "docs_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "notice" ], "properties": { "notice": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The email field was missing or invalid, or an optional attribution field was not a string of at most 120 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many free-tier keys were created from this network today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The signup request could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/keys/rotate": { "post": { "tags": [ "Keys" ], "operationId": "rotateApiKey", "summary": "Rotate your API key", "description": "Replaces the secret of the key that authenticates the request. The old key stops working immediately; plan, rate limit, usage, and billing carry over. Free keys receive the new key in the response. Keys on a paid subscription never receive it in the response: it is emailed to the subscription's billing address, so a leaked key cannot be used to take over the subscription. Limited to 5 rotations per key per 24 hours. Key-management calls are not metered and are allowed even when a free key has used its monthly quota.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The key was rotated.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "key_hint", "previous_key_hint", "delivery" ], "properties": { "key": { "type": "string", "pattern": "^cf_(live|test)_[0-9a-f]{64}$", "description": "The new raw key. Present only when `delivery` is `response` (free keys); shown once and never retrievable again." }, "key_hint": { "type": "string", "maxLength": 8, "description": "Last characters of the new key." }, "previous_key_hint": { "type": "string", "maxLength": 8, "description": "Last characters of the key that stopped working." }, "delivery": { "type": "string", "enum": [ "response", "email" ], "description": "`response`: the new key is in `data.key`. `email`: the key belongs to a paid subscription, so the new key was emailed to its billing address instead." }, "delivered_to": { "type": "string", "description": "Masked billing address the new key was emailed to. Present only when `delivery` is `email`." } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "notice" ], "properties": { "notice": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "The key was rotated 5 times in the last 24 hours (RATE_LIMIT_EXCEEDED), or it exceeded its one-minute request limit. The current key keeps working.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The rotation could not be completed or confirmed. Check whether the current key still works before retrying.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "A paid key was rotated, but the email carrying the new key could not be sent. Request a recovery token with POST /v1/keys/recover.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/keys/revoke": { "post": { "tags": [ "Keys" ], "operationId": "revokeApiKey", "summary": "Revoke your API key", "description": "Permanently revokes the key that authenticates the request; it fails authentication immediately and cannot be restored. A key that pays for an active subscription is refused with 409 SUBSCRIPTION_ACTIVE unless the body sets cancel_subscription to true, which cancels the subscription first and then revokes the key. To replace a leaked key and keep the subscription, rotate it instead.", "security": [ { "apiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancel_subscription": { "type": "boolean", "default": false, "description": "Required as `true` when the key pays for an active subscription: the subscription is cancelled immediately (no refund of the current month; overage already used is invoiced), then the key is revoked. Ignored for free keys." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The key was revoked.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revoked", "key_hint", "subscription_cancelled" ], "properties": { "revoked": { "type": "boolean", "const": true }, "key_hint": { "type": "string", "maxLength": 8 }, "subscription_cancelled": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The body was not a JSON object, or cancel_subscription was not a boolean.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "SUBSCRIPTION_ACTIVE: the key pays for an active subscription. Resend with {\"cancel_subscription\": true} to end it, or rotate the key instead.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The revocation could not be completed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The subscription could not be cancelled, so the key was not revoked.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/keys/recover": { "post": { "tags": [ "Keys" ], "operationId": "requestKeyRecovery", "summary": "Email a key recovery token", "description": "For a paid key whose secret was lost. If the email is the billing address of an active or past-due subscription, a single-use recovery token that expires in 30 minutes is emailed to it. The answer is the same 202 whether or not the address matched. Free keys are not recoverable; create a new one with POST /v1/signup. Limited to 10 requests per client IP per day and 3 tokens per key per hour.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "The billing email address of a paid Foresight API subscription." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted. A token was emailed if the address belongs to a paid subscription.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean", "const": true } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "notice" ], "properties": { "notice": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The email field was missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many recovery requests from this network today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Key recovery could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/keys/recover/confirm": { "post": { "tags": [ "Keys" ], "operationId": "confirmKeyRecovery", "summary": "Redeem a key recovery token", "description": "Consumes the emailed recovery token and replaces the key's secret. The old key stops working immediately, and the new key is emailed to the billing address, never returned in the response. Each token works once. Shares the recovery rate limit of 10 requests per client IP per day.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^cfr_[0-9a-f]{64}$", "description": "The single-use recovery token from the recovery email." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The key was replaced and the new key was emailed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "key_hint", "previous_key_hint", "delivery" ], "properties": { "key": { "type": "string", "pattern": "^cf_(live|test)_[0-9a-f]{64}$", "description": "The new raw key. Present only when `delivery` is `response` (free keys); shown once and never retrievable again." }, "key_hint": { "type": "string", "maxLength": 8, "description": "Last characters of the new key." }, "previous_key_hint": { "type": "string", "maxLength": 8, "description": "Last characters of the key that stopped working." }, "delivery": { "type": "string", "enum": [ "response", "email" ], "description": "`response`: the new key is in `data.key`. `email`: the key belongs to a paid subscription, so the new key was emailed to its billing address instead." }, "delivered_to": { "type": "string", "description": "Masked billing address the new key was emailed to. Present only when `delivery` is `email`." } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "notice" ], "properties": { "notice": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The token is malformed, invalid, expired, or already used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many recovery requests from this network today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Key recovery could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The key was replaced, but the email carrying the new key could not be sent. Request a new token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/observations": { "get": { "tags": [ "Observations" ], "operationId": "listObservations", "summary": "List observations", "description": "Period convention (FRED/BLS): period_start is the first day of the period and period_end its last day, derived from period_type. A monthly June 2026 value spans 2026-06-01..2026-06-30; quarterly 2026-Q1 spans 2026-01-01..2026-03-31; annual 2025 spans 2025-01-01..2025-12-31. Daily and weekly rows carry the source date in both fields (sources date weeks by their start or by their end).", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "dynamic", "min": "0.01", "max": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicator", "in": "query", "required": true, "description": "Indicator code or concept code. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "include_revisions", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "transform", "in": "query", "required": false, "description": "Apply a query-time transform: yoy, mom, qoq, index:YYYY-MM-DD, log. Comparators (and the index base period) are read from the full series, even when they lie before the returned page or before start_date; a row yields null only when its comparator does not exist in the series. When frequency is also supplied, resampling runs first and the transform runs at the target frequency. Cannot be combined with include_revisions=true.", "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "required": false, "description": "Downsample to monthly, quarterly, or annual buckets before transform. Buckets are labeled by calendar start date; weekly rows are assigned by period_start. limit, offset and meta.total count OUTPUT buckets over the whole requested range, and each returned bucket aggregates every source row in it. The series' newest bucket is omitted while incomplete (the last source observation plus one source period does not pass the bucket end; meta.resample.dropped_incomplete_trailing).", "schema": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] } }, { "name": "resample_method", "in": "query", "required": false, "description": "Aggregation method for frequency resampling. Defaults to mean. Must be used with frequency. Null values are excluded from mean and sum; last uses the last non-null value; all-null buckets are retained with null.", "schema": { "type": "string", "enum": [ "mean", "last", "sum" ], "default": "mean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Observation rows matching the query.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Observation" }, { "type": "object", "required": [ "period_start", "period_end", "period_type", "value" ], "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "period_type": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "value": { "type": [ "number", "null" ] } }, "additionalProperties": false } ] } }, "meta": { "type": "object", "required": [ "indicator", "region", "unit", "total", "limit", "offset" ], "properties": { "indicator": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0, "maximum": 1000 }, "offset": { "type": "integer", "minimum": 0 }, "source_attribution": { "type": "string" }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "resample": { "type": "object", "required": [ "method", "from", "to" ], "properties": { "method": { "type": "string", "enum": [ "mean", "last", "sum" ] }, "from": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "annual" ] }, "to": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "dropped_incomplete_trailing": { "type": "boolean" }, "dropped_page_boundary_buckets": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "transform": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "yoy", "mom", "qoq", "log" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "base" ], "properties": { "kind": { "type": "string", "const": "index" }, "base": { "type": "string", "format": "date" } }, "additionalProperties": false } ] }, "concept": { "type": "object", "required": [ "code", "resolved_indicator", "source" ], "properties": { "code": { "type": "string" }, "resolved_indicator": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": false }, "retired": { "type": "object", "description": "Present when the series has been retired from the catalog (orphaned, superseded, discontinued upstream or never ingested). Its stored data is still served; it no longer updates.", "required": [ "retired_at", "reason" ], "properties": { "retired_at": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "replaced_by": { "type": "string", "description": "The indicator code that replaces this series, when there is one." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "202": { "$ref": "#/components/responses/ProvisioningStarted" }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the indicator is premium and the key does not carry that grant; error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes the RESOLVED region — which is the indicator's default region when the region parameter is omitted. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested indicator or region resource was not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Observation data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/flows": { "get": { "tags": [ "Flows" ], "operationId": "listFlows", "summary": "List region-to-region flows", "description": "Returns directed origin-to-destination flow rows for a region filter. When period is omitted, the latest period_start available for the filter is used and reported in meta.period.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.01" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "origin", "in": "query", "required": false, "description": "Origin region code. At least one of origin or destination is required.", "schema": { "type": "string" } }, { "name": "destination", "in": "query", "required": false, "description": "Destination region code. At least one of origin or destination is required.", "schema": { "type": "string" } }, { "name": "measure", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Flow rows matching the query, ordered by value descending.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowsResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes a region named in origin or destination. Counterparty regions that appear in the payload are not separately gated: a flow is a property of the origin/destination PAIR and one endpoint is always optional, so gating both ends would deny every cross-region query. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested origin or destination region was not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Flow data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/panel": { "get": { "tags": [ "Observations" ], "operationId": "getPanel", "summary": "Return an aligned multi-series panel", "description": "Returns one aligned date grid with one column per requested indicator. Without frequency, panels pass through when every series shares one native daily, monthly, quarterly, or annual frequency; mixed-frequency panels use the coarsest valid native frequency and resample finer series. Weekly panels must pass frequency=monthly or coarser. missing=drop uses the intersection grid; missing=ffill uses the union grid and carries each region/series value forward while leading gaps remain null.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicators", "in": "query", "required": true, "description": "Comma-separated indicator codes or concept codes. Concept codes are resolved per requested region. Duplicates are deduped; at most 10 unique indicators are accepted. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "One region code for the whole panel. Omit only when every indicator has a resolvable default region.", "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "required": false, "description": "Optional shared frequency. Accepted values are daily, monthly, quarterly, and annual. daily is passthrough-only and requires every series to be natively daily; monthly, quarterly, and annual are resampling targets. Series finer than a resampling target are downsampled; series coarser than the target return 400.", "schema": { "type": "string", "enum": [ "daily", "monthly", "quarterly", "annual" ] } }, { "name": "resample_method", "in": "query", "required": false, "description": "Aggregation method for panel resampling. Defaults to mean and applies globally to every resampled series.", "schema": { "type": "string", "enum": [ "mean", "last", "sum" ], "default": "mean" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "missing", "in": "query", "required": false, "description": "drop keeps dates present in every series. ffill aligns to the union of region/date keys and carries each column forward independently; leading gaps remain null.", "schema": { "type": "string", "enum": [ "drop", "ffill" ], "default": "drop" } } ], "responses": { "200": { "description": "Aligned panel response.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanelResponse" } } } }, "400": { "description": "A query parameter was invalid, a series had unknown native frequency, frequency=daily was requested for non-daily series, a series was coarser than the requested target, weekly needed an explicit monthly-or-coarser target, or the 5,000 grid-point limit was exceeded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when at least one requested premium indicator is not allowed for the API key; error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes the RESOLVED region — which is the indicator's default region when the region parameter is omitted. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "One or more requested indicators were unknown. Panel v1 does not provision or write the miss ledger.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The panel could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/observations/latest": { "get": { "tags": [ "Observations" ], "operationId": "getLatestObservations", "summary": "Get latest observation", "description": "Use either indicator for the legacy single-indicator response envelope or indicators for a comma-separated batch of up to 20 indicator codes. Batch responses return data and per-indicator errors.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "dynamic", "min": "0.01", "max": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicator", "in": "query", "required": false, "description": "Indicator code or concept code. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "indicators", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated indicator codes or concept codes for batch latest lookup. Maximum 20. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest observation for a single indicator, or a successful batch with no per-indicator errors.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/LatestObservation" }, { "type": "null" } ] }, "meta": { "type": "object", "required": [ "indicator", "region", "unit", "total", "limit", "offset" ], "properties": { "indicator": { "type": "string" }, "region": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 1 }, "limit": { "type": "integer", "const": 1 }, "offset": { "type": "integer", "const": 0 }, "source_attribution": { "type": "string" }, "concept": { "type": "object", "required": [ "code", "resolved_indicator", "source" ], "properties": { "code": { "type": "string" }, "resolved_indicator": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": false }, "retired": { "type": "object", "description": "Present when the series has been retired from the catalog (orphaned, superseded, discontinued upstream or never ingested). Its stored data is still served; it no longer updates.", "required": [ "retired_at", "reason" ], "properties": { "retired_at": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "replaced_by": { "type": "string", "description": "The indicator code that replaces this series, when there is one." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "data", "errors" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LatestObservation" } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "indicator", "code", "message" ], "properties": { "indicator": { "type": "string" }, "code": { "type": "string", "enum": [ "INVALID_PARAMETER", "RESOURCE_NOT_FOUND", "CATEGORY_NOT_ALLOWED", "REGION_NOT_ALLOWED" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "additionalProperties": false } ] } } } }, "202": { "$ref": "#/components/responses/ProvisioningStarted" }, "207": { "description": "Batch latest response with one or more per-indicator errors.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "errors" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LatestObservation" } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "indicator", "code", "message" ], "properties": { "indicator": { "type": "string" }, "code": { "type": "string", "enum": [ "INVALID_PARAMETER", "RESOURCE_NOT_FOUND", "CATEGORY_NOT_ALLOWED", "REGION_NOT_ALLOWED" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the indicator is premium and the key does not carry that grant; error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes the RESOLVED region — which is the indicator's default region when the region parameter is omitted. In the multi-indicator batch form the same denials are reported per indicator in the 207 errors array rather than as a whole-request 403. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested indicator or region resource was not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Latest observation data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/insights": { "get": { "tags": [ "Insights" ], "operationId": "getInsights", "summary": "Compute descriptive facts and active signals for an indicator series", "description": "Returns deterministic computed facts over the requested observation window, plus active signals when the signals repository is available.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "dynamic", "min": "0.01", "max": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicator", "in": "query", "required": true, "description": "Indicator code or concept code. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "standard", "briefing" ], "default": "standard" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(all|[1-9][0-9]*[dmy])$", "default": "all", "examples": [ "90d", "12m", "5y", "all" ] } } ], "responses": { "200": { "description": "Salience-ranked computed facts and active signals for the series.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "facts", "signals", "meta" ], "properties": { "facts": { "type": "array", "items": { "$ref": "#/components/schemas/InsightFact" } }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/InsightSignal" } }, "meta": { "type": "object", "required": [ "indicator", "region", "unit", "window", "observation_count" ], "properties": { "indicator": { "type": "string" }, "region": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "window": { "type": "string" }, "observation_count": { "type": "integer", "minimum": 0 }, "source_attribution": { "type": "string" }, "concept": { "type": "object", "required": [ "code", "resolved_indicator", "source" ], "properties": { "code": { "type": "string" }, "resolved_indicator": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the API key does not include access to the indicator category; error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes the RESOLVED region — which is the indicator's default region when the region parameter is omitted. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested indicator or region resource was not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Insight data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ask": { "get": { "tags": [ "Insights" ], "operationId": "ask", "summary": "Answer a natural-language question using Foresight data", "description": "Coverage-gated ask endpoint. Questions with no catalog coverage return no_coverage and are not priced for x402.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "dynamic", "min": "0.25", "max": "1.50" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(all|[1-9][0-9]*[dmy])$", "examples": [ "90d", "12m", "5y", "all" ] } } ], "responses": { "200": { "description": "Ask result, no-data response, or free no-coverage response.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "answer", "citations", "resolved", "grounded", "truncated", "status", "meta" ], "properties": { "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "required": [ "tool", "args", "summary" ], "properties": { "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" } }, "additionalProperties": false } }, "resolved": { "type": "object", "required": [ "indicators", "regions", "window" ], "properties": { "indicators": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string" } }, "window": { "type": "string" } }, "additionalProperties": false }, "grounded": { "type": "boolean" }, "truncated": { "type": "boolean" }, "status": { "type": "string", "const": "ok" }, "meta": { "type": "object", "required": [ "model", "rounds", "toolCalls", "depth" ], "properties": { "model": { "type": "string" }, "rounds": { "type": "integer", "minimum": 0 }, "toolCalls": { "type": "integer", "minimum": 0 }, "depth": { "type": "string", "enum": [ "standard", "briefing" ], "default": "standard" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "answer", "status", "message", "matched" ], "properties": { "answer": { "type": "null" }, "status": { "type": "string", "const": "no_coverage" }, "message": { "type": "string" }, "matched": { "type": "object", "required": [ "regions" ], "properties": { "regions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "answer", "status", "message" ], "properties": { "answer": { "type": "null" }, "status": { "type": "string", "const": "no_data" }, "message": { "type": "string" } }, "additionalProperties": false } ] } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code REGION_NOT_ALLOWED when the key's allowed_regions grant excludes the region hint. The same grant is enforced on every region the answer's own tool calls reach, so a question about an ungranted region returns no data rather than an answer. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The ask endpoint is disabled or temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/briefings": { "get": { "tags": [ "Insights" ], "operationId": "listBriefings", "summary": "List saved ask briefings for the API key", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Briefings owned by the API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Briefing" } } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QuotaExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Insights" ], "operationId": "createBriefing", "summary": "Create a saved scheduled ask briefing", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "question", "cadence" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": "string" }, "window": { "type": "string", "pattern": "^(all|[1-9][0-9]*[dmy])$" }, "cadence": { "type": "string", "enum": [ "daily", "weekly" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Briefing created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Briefing" } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not include creative-foresight premium access. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/briefings/public": { "get": { "tags": [ "Insights" ], "operationId": "listPublicBriefings", "summary": "List curated public briefings", "description": "Free public catalog of CF-owned curated briefings. Reading a briefing run is priced separately on /v1/briefings/public/{slug}.", "security": [], "responses": { "200": { "description": "Public curated briefing catalog.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBriefingSummary" } } }, "additionalProperties": false } } } }, "500": { "description": "The public briefing catalog could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/briefings/public/{slug}": { "get": { "tags": [ "Insights" ], "operationId": "getPublicBriefing", "summary": "Read the latest successful run for a curated public briefing", "description": "Requires either an API key with creative-foresight category access or an x402 payment. Unknown, private, and empty briefing slugs answer the same x402 challenge and then return 404 after payment verification, without settling the payment.", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.10" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest successful public briefing run.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PublicBriefingRead" } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the key does not carry the creative-foresight premium grant; REGION_NOT_ALLOWED when the briefing declares a region and the key's allowed_regions grant excludes it. A curated briefing that declares no region resolves no region and is not gated, and an anonymous x402/L402 payer carries no grant at all, so neither is ever refused on region. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The public briefing slug was unknown, private, or had no successful run. A key whose allowed_regions grant excludes the briefing receives 403 rather than 404: the whole curated catalog is already listed unauthenticated by GET /v1/briefings/public, so separating the two discloses nothing new.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/briefings/{id}": { "get": { "tags": [ "Insights" ], "operationId": "getBriefing", "summary": "Get a saved ask briefing and latest run", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Server-generated briefing UUID. `public` is a sibling static path segment rather than a briefing id, so a request under /v1/briefings/public/ never reaches this operation.", "schema": { "type": "string", "format": "uuid", "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}$" } } ], "responses": { "200": { "description": "Briefing detail owned by the API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BriefingDetail" } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QuotaExceeded" }, "404": { "description": "The briefing was not found for this API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Insights" ], "operationId": "deleteBriefing", "summary": "Delete a saved ask briefing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Server-generated briefing UUID. `public` is a sibling static path segment rather than a briefing id, so a request under /v1/briefings/public/ never reaches this operation.", "schema": { "type": "string", "format": "uuid", "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}$" } } ], "responses": { "204": { "description": "Briefing deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QuotaExceeded" }, "404": { "description": "The briefing was not found for this API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/briefings/{id}/runs": { "get": { "tags": [ "Insights" ], "operationId": "listBriefingRuns", "summary": "List run history for a saved ask briefing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Server-generated briefing UUID. `public` is a sibling static path segment rather than a briefing id, so a request under /v1/briefings/public/ never reaches this operation.", "schema": { "type": "string", "format": "uuid", "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}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Run history for the briefing.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BriefingRun" } } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QuotaExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/active": { "get": { "tags": [ "Signals" ], "operationId": "listActiveSignals", "summary": "List active premium signals", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicator", "in": "query", "required": false, "description": "Indicator code or concept code. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "acceleration", "extreme", "trend_break" ] } }, { "name": "strength", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "weak", "neutral", "strong" ], "default": "neutral" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Open signal intervals matching the query.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "meta": { "type": "object", "required": [ "count", "limit", "filters" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "next_cursor": { "type": "string" }, "filters": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the API key does not include creative-foresight premium signal access; REGION_NOT_ALLOWED when it carries an allowed_regions grant that excludes an explicitly requested region. A request that omits region is narrowed to the granted regions rather than refused, because refusing an unfiltered list would make the endpoint unusable for a scoped key. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Signal data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/signals": { "get": { "tags": [ "Signals" ], "operationId": "listSignals", "summary": "List premium signal intervals", "security": [ { "apiKey": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "indicator", "in": "query", "required": false, "description": "Indicator code or concept code. Concept codes such as population, gdp, median_income, median_home_value, unemployment_rate, labor_force, and employed are accepted; responses resolved through a concept include meta.concept provenance.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "acceleration", "extreme", "trend_break" ] } }, { "name": "strength", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "weak", "neutral", "strong" ], "default": "neutral" } }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signal intervals matching the query.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "meta": { "type": "object", "required": [ "count", "limit", "filters" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "next_cursor": { "type": "string" }, "filters": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/InvalidParameterKeyGated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "The API key is not allowed to read this resource. error.code CATEGORY_NOT_ALLOWED when the API key does not include creative-foresight premium signal access; REGION_NOT_ALLOWED when it carries an allowed_regions grant that excludes an explicitly requested region. A request that omits region is narrowed to the granted regions rather than refused, because refusing an unfiltered list would make the endpoint unusable for a scoped key. A free-tier key that has exhausted its monthly request quota also receives 403 here, with error.code UPGRADE_REQUIRED.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Signal data could not be loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ping": { "get": { "tags": [ "Diagnostics" ], "operationId": "ping", "summary": "Validate bearer API key connectivity", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The bearer API key is valid.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "keyName" ], "properties": { "ok": { "type": "boolean", "const": true }, "keyName": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QuotaExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }