docs/api/PredictionService.openapi.json

Rama main · réplica de lectura del repositorio original.

{"components":{"schemas":{"BillingVerificationError":{"description":"Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After.","properties":{"code":{"description":"Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.","enum":["renewal_verification_pending","renewal_verification_failed","entitlement_verification_unavailable"],"type":"string"},"error":{"description":"Human-readable billing-verification failure reason.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.","format":"int32","type":"integer"}},"required":["error","code"],"type":"object"},"Error":{"description":"Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.","properties":{"message":{"description":"Error message (e.g., 'user not found', 'database connection failed')","type":"string"}},"type":"object"},"FieldViolation":{"description":"FieldViolation describes a single validation error for a specific field.","properties":{"description":{"description":"Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')","type":"string"},"field":{"description":"The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')","type":"string"}},"required":["field","description"],"type":"object"},"ForbiddenError":{"description":"Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.","properties":{"code":{"description":"Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).","enum":["subscription_lapsed"],"type":"string"},"currentTier":{"description":"Caller entitlement tier when known.","format":"int32","type":"integer"},"error":{"description":"Human-readable entitlement failure reason.","type":"string"},"planKey":{"description":"Caller plan key when known.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint.","format":"int32","type":"integer"}},"required":["error"],"type":"object"},"GatewayError":{"description":"Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.","properties":{"error":{"description":"Gateway error reason or structured gateway failure details.","oneOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]}},"required":["error"],"type":"object"},"InvalidRequestBodyError":{"description":"Returned when a JSON POST request body is empty or malformed.","properties":{"message":{"description":"Invalid request body","type":"string"}},"required":["message"],"type":"object"},"JmespathProjectionError":{"description":"Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.","properties":{"_jmespath_error":{"description":"Projection error discriminator and details.","type":"string"},"original_keys":{"description":"Top-level keys or shape of the unprojected response.","items":{"type":"string"},"type":"array"}},"required":["_jmespath_error","original_keys"],"type":"object"},"ListPredictionMarketsRequest":{"description":"ListPredictionMarketsRequest specifies filters for retrieving prediction markets.","properties":{"category":{"description":"Optional category filter (e.g., \"Politics\").","type":"string"},"cursor":{"description":"Cursor for next page.\n Accepted but currently ignored; no-op until this handler supports the parameter.","type":"string"},"minLiquidity":{"description":"Optional minimum liquidity (resting order-book depth in USD). When above 0,\n only markets with liquidity at or above this value are returned; markets\n without a liquidity value are dropped. Applied before page_size.","format":"double","minimum":0,"type":"number"},"pageSize":{"description":"Maximum items per page (1-100).","format":"int32","type":"integer"},"query":{"description":"Optional search query for market titles.","type":"string"}},"type":"object"},"ListPredictionMarketsResponse":{"description":"ListPredictionMarketsResponse contains prediction markets matching the request.","properties":{"dataAvailable":{"description":"True when markets were evaluated against a seed snapshot. False means an\n empty payload is graceful degradation because the snapshot is unavailable.","type":"boolean"},"fetchedAt":{"description":"Time the seed snapshot was fetched, as Unix epoch milliseconds. A value of\n 0 means the snapshot is unavailable/degraded, not that there are confirmed\n zero matching markets.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"markets":{"items":{"$ref":"#/components/schemas/PredictionMarket"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}},"type":"object"},"PaginationResponse":{"description":"PaginationResponse contains pagination metadata returned alongside list results.","properties":{"nextCursor":{"description":"Cursor for fetching the next page. Empty string indicates no more pages.","type":"string"},"totalCount":{"description":"Total count of items matching the query, if known. Zero if the total is unknown.","format":"int32","type":"integer"}},"type":"object"},"PredictionMarket":{"description":"PredictionMarket represents a prediction market contract.","properties":{"category":{"description":"Market category (e.g., \"Politics\", \"Crypto\", \"Sports\").","type":"string"},"closesAt":{"description":"Market close time, as Unix epoch milliseconds. Zero if no expiry.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"id":{"description":"Unique market identifier or slug.","minLength":1,"type":"string"},"liquidity":{"description":"Resting order-book depth in USD, measured per venue: Polymarket CLOB\n liquidity, or the sum of price times size over every Kalshi yes and no bid.\n Absent when the venue reports none or the order book could not be fetched.","format":"double","minimum":0,"type":"number"},"source":{"description":"Source platform for prediction market data.","enum":["MARKET_SOURCE_UNSPECIFIED","MARKET_SOURCE_POLYMARKET","MARKET_SOURCE_KALSHI"],"type":"string"},"title":{"description":"Market question or title.","type":"string"},"url":{"description":"URL to the market page.","type":"string"},"volume":{"description":"Trading volume in USD.","format":"double","minimum":0,"type":"number"},"yesPrice":{"description":"Current \"Yes\" price (0.0 to 1.0, representing probability).","format":"double","maximum":1,"minimum":0,"type":"number"},"yesPriceChange24h":{"description":"Upstream 24-hour Yes price change on the probability scale. Absent if unavailable.","format":"double","maximum":1,"minimum":-1,"type":"number"},"yesPriceChange7d":{"description":"Upstream 7-day Yes price change on the probability scale. Polymarket only.","format":"double","maximum":1,"minimum":-1,"type":"number"}},"required":["id"],"type":"object"},"RateLimitError":{"description":"Returned when a gateway or handler rate limit rejects the request.","properties":{"error":{"description":"Human-readable rate-limit failure reason.","type":"string"}},"required":["error"],"type":"object"},"UnauthorizedError":{"description":"Returned when the API key is missing, malformed, or lacks current API access.","properties":{"error":{"description":"Human-readable error message.","type":"string"}},"required":["error"],"type":"object"},"ValidationError":{"description":"ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.","properties":{"violations":{"description":"List of validation violations","items":{"$ref":"#/components/schemas/FieldViolation"},"type":"array"}},"required":["violations"],"type":"object"}},"securitySchemes":{"ApiKeyHeader":{"description":"Alias header for the WorldMonitor API key (X-WorldMonitor-Key).","in":"header","name":"X-Api-Key","type":"apiKey"},"WorldMonitorKey":{"description":"User-issued WorldMonitor API key.","in":"header","name":"X-WorldMonitor-Key","type":"apiKey"}}},"info":{"title":"PredictionService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/prediction/v1/list-prediction-markets":{"get":{"description":"ListPredictionMarkets retrieves active prediction markets from seeded market snapshots.\n Empty markets with fetched_at=0 or data_available=false means the seed\n snapshot is unavailable/degraded, not that there are confirmed zero markets.","operationId":"ListPredictionMarkets","parameters":[{"description":"Maximum items per page (1-100).","example":25,"in":"query","name":"page_size","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Cursor for next page.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":"next-page-token","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Optional category filter (e.g., \"Politics\").","example":"ai","in":"query","name":"category","required":false,"schema":{"enum":["ai","tech","crypto","science","economy","fed","inflation","interest-rates","recession","trade","tariffs","debt-ceiling"],"type":"string"}},{"description":"Optional search query for market titles.","example":"supply chain risk","in":"query","name":"query","required":false,"schema":{"type":"string"}},{"description":"Optional minimum liquidity (resting order-book depth in USD). When above 0,\n only markets with liquidity at or above this value are returned; markets\n without a liquidity value are dropped. Applied before page_size.","example":1.5,"in":"query","name":"min_liquidity","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"dataAvailable":true,"fetchedAt":1717200000000,"markets":[{"category":"cs.AI","closesAt":1717200000000,"id":"example-id","liquidity":1.5,"source":"MARKET_SOURCE_POLYMARKET","title":"example"}],"pagination":{"nextCursor":"next-page-token","totalCount":1}},"schema":{"$ref":"#/components/schemas/ListPredictionMarketsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListPredictionMarkets","tags":["PredictionService"]}}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]}],"servers":[{"url":"https://api.worldmonitor.app"}]}