docs/api/ForecastService.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"},"CalibrationInfo":{"properties":{"drift":{"format":"double","type":"number"},"internalProbability":{"description":"Probability before the market blend.","format":"double","type":"number"},"marketBlendedProbability":{"description":"Probability after the market blend and domain cap.","format":"double","type":"number"},"marketPrice":{"format":"double","type":"number"},"marketTitle":{"type":"string"},"source":{"type":"string"}},"type":"object"},"CascadeEffect":{"properties":{"domain":{"type":"string"},"effect":{"type":"string"},"probability":{"format":"double","type":"number"}},"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"},"Forecast":{"properties":{"calibration":{"$ref":"#/components/schemas/CalibrationInfo"},"cascades":{"items":{"$ref":"#/components/schemas/CascadeEffect"},"type":"array"},"caseFile":{"$ref":"#/components/schemas/ForecastCase"},"confidence":{"format":"double","type":"number"},"createdAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"demotedBySimulation":{"description":"True when a negative adjustment crossed the 0.50 acceptance threshold.","type":"boolean"},"domain":{"type":"string"},"feedSummary":{"type":"string"},"id":{"type":"string"},"perspectives":{"$ref":"#/components/schemas/Perspectives"},"priorProbability":{"format":"double","type":"number"},"probability":{"format":"double","type":"number"},"projections":{"$ref":"#/components/schemas/Projections","deprecated":true},"region":{"type":"string"},"resolution":{"$ref":"#/components/schemas/ResolutionSpec"},"scenario":{"type":"string"},"scoredHorizons":{"items":{"description":"Horizons whose projection is graded.","type":"string"},"type":"array"},"signals":{"items":{"$ref":"#/components/schemas/ForecastSignal"},"type":"array"},"simPathConfidence":{"description":"Confidence in [0, 1] of the matched simulation top path; 0 when not set.","format":"double","type":"number"},"simulationAdjustment":{"description":"Score delta from the deep simulation pipeline: +0.08 to +0.12, or\n -0.12 or -0.15; 0 when it has not run.","format":"double","type":"number"},"timeHorizon":{"type":"string"},"title":{"type":"string"},"trend":{"description":"\"rising\", \"falling\", or \"stable\" versus the prior snapshot, with a\n +/-0.05 deadband on the probability delta.","type":"string"},"updatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"ForecastActor":{"properties":{"category":{"type":"string"},"constraints":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"influenceScore":{"format":"double","type":"number"},"likelyActions":{"items":{"type":"string"},"type":"array"},"name":{"type":"string"},"objectives":{"items":{"type":"string"},"type":"array"},"role":{"type":"string"}},"type":"object"},"ForecastBranch":{"properties":{"kind":{"type":"string"},"outcome":{"type":"string"},"projectedProbability":{"format":"double","type":"number"},"rounds":{"items":{"$ref":"#/components/schemas/ForecastBranchRound"},"type":"array"},"summary":{"type":"string"},"title":{"type":"string"}},"type":"object"},"ForecastBranchRound":{"properties":{"actorMoves":{"items":{"type":"string"},"type":"array"},"developments":{"items":{"type":"string"},"type":"array"},"focus":{"type":"string"},"probabilityShift":{"format":"double","type":"number"},"round":{"format":"int32","type":"integer"}},"type":"object"},"ForecastCase":{"properties":{"actorLenses":{"items":{"type":"string"},"type":"array"},"actors":{"items":{"$ref":"#/components/schemas/ForecastActor"},"type":"array"},"baseCase":{"type":"string"},"branches":{"items":{"$ref":"#/components/schemas/ForecastBranch"},"type":"array"},"changeItems":{"items":{"type":"string"},"type":"array"},"changeSummary":{"type":"string"},"contrarianCase":{"type":"string"},"counterEvidence":{"items":{"$ref":"#/components/schemas/ForecastCaseEvidence"},"type":"array"},"escalatoryCase":{"type":"string"},"supportingEvidence":{"items":{"$ref":"#/components/schemas/ForecastCaseEvidence"},"type":"array"},"triggers":{"items":{"type":"string"},"type":"array"},"worldState":{"$ref":"#/components/schemas/ForecastWorldState"}},"type":"object"},"ForecastCaseEvidence":{"properties":{"summary":{"type":"string"},"type":{"type":"string"},"weight":{"format":"double","type":"number"}},"type":"object"},"ForecastSignal":{"properties":{"type":{"type":"string"},"value":{"type":"string"},"weight":{"format":"double","type":"number"}},"type":"object"},"ForecastWorldState":{"properties":{"activePressures":{"items":{"type":"string"},"type":"array"},"keyUnknowns":{"items":{"type":"string"},"type":"array"},"stabilizers":{"items":{"type":"string"},"type":"array"},"summary":{"type":"string"}},"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"},"GetForecastScorecardRequest":{"type":"object"},"GetForecastScorecardResponse":{"properties":{"byDomain":{"items":{"$ref":"#/components/schemas/ScorecardDomainGroup"},"type":"array"},"byGenerationOrigin":{"items":{"$ref":"#/components/schemas/ScorecardGenerationOriginGroup"},"type":"array"},"calibration":{"items":{"$ref":"#/components/schemas/ScorecardCalibrationBucket"},"type":"array"},"degraded":{"type":"boolean"},"error":{"type":"string"},"familyOutcomes":{"items":{"$ref":"#/components/schemas/ScorecardFamilyOutcome"},"type":"array"},"funnel":{"$ref":"#/components/schemas/ScorecardFunnel"},"generatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"marketAlerts":{"$ref":"#/components/schemas/MarketAlertScorecard"},"methodology":{"type":"string"},"overall":{"$ref":"#/components/schemas/ScorecardSummary"},"publishedByDomain":{"items":{"$ref":"#/components/schemas/ScorecardPublishedDomain"},"type":"array"},"receipts":{"items":{"$ref":"#/components/schemas/ScorecardReceipt"},"type":"array"},"rollingWindowDays":{"format":"int32","type":"integer"},"schemaVersion":{"format":"int32","type":"integer"},"skill":{"$ref":"#/components/schemas/ScorecardSkill"},"stale":{"type":"boolean"},"totals":{"$ref":"#/components/schemas/ScorecardTotals"},"uncertainty":{"$ref":"#/components/schemas/ScorecardUncertainty"},"underAudit":{"$ref":"#/components/schemas/ScorecardUnderAudit"},"vsMarketSkill":{"$ref":"#/components/schemas/ScorecardMarketSkill"}},"type":"object"},"GetForecastsRequest":{"properties":{"domain":{"description":"Forecast domain to retrieve, such as geopolitics, markets, or climate.","type":"string"},"region":{"description":"Optional geographic or thematic region filter for forecasts.","type":"string"}},"type":"object"},"GetForecastsResponse":{"properties":{"degraded":{"description":"True when the forecast backend could not read the canonical cache.\n Distinguishes an outage from a healthy empty forecast set.","type":"boolean"},"error":{"description":"Stable machine-readable reason when degraded=true, empty otherwise.\n Value: \"forecast_backend_unavailable\" on Redis/backend read failures.","type":"string"},"forecasts":{"items":{"$ref":"#/components/schemas/Forecast"},"type":"array"},"generatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"stale":{"description":"Always false: get-forecasts has no stale fallback.","type":"boolean"}},"type":"object"},"GetSimulationOutcomeRequest":{"properties":{"runId":{"description":"Optional run ID (epoch ms, hyphen, 1-64 char suffix; max 128). Returns that\n run's outcome within 24h retention, processing=true while it is queued, or\n the latest outcome with a note. Empty returns the latest outcome.","example":"1789387200000-abc123","examples":["1789387200000-abc123"],"maxLength":128,"pattern":"^([0-9]{13,}-[A-Za-z0-9-]{1,64})?$","type":"string"}},"type":"object"},"GetSimulationOutcomeResponse":{"properties":{"allTheatersFailed":{"description":"True when eligible_theater_count \u003e 0 and no theater produced an outcome.","type":"boolean"},"completionStatus":{"description":"Machine-readable completion status. Current values:\n \"completed\", \"partial\", \"no_eligible_theaters\", or \"all_theaters_failed\".","type":"string"},"eligibleTheaterCount":{"description":"Number of theaters eligible for simulation in the package used by this outcome.","format":"int32","type":"integer"},"error":{"description":"Populated when the Redis lookup failed. Distinguish from healthy not-found (found=false, error=\"\").\n Value: \"redis_unavailable\" on Redis errors.","type":"string"},"failedTheaterCount":{"description":"Number of eligible theaters that failed before producing a Round 2 result.","format":"int32","type":"integer"},"found":{"type":"boolean"},"generatedAt":{"description":"Unix timestamp in milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"note":{"description":"Set when run_id was supplied but the latest outcome is returned instead; the\n text says why (run expired or not found, or its by-run record failed).","type":"string"},"processing":{"description":"True when the supplied runId is still queued, as opposed to expired.","type":"boolean"},"runId":{"type":"string"},"schemaVersion":{"type":"string"},"theaterCount":{"format":"int32","type":"integer"},"theaterSummariesJson":{"description":"JSON-encoded Array\u003c{ theaterId, theaterLabel, stateKind, topPaths: [{label,\n summary, confidence, keyActors}], dominantReactions, stabilizers,\n invalidators }\u003e; empty when found=false.","type":"string"}},"type":"object"},"GetSimulationPackageRequest":{"properties":{"runId":{"description":"Optional run identifier. It does not select a package yet: the latest is\n always returned, and note says when it differs.","type":"string"}},"type":"object"},"GetSimulationPackageResponse":{"properties":{"error":{"description":"Populated when the Redis lookup failed. Distinguish from healthy not-found (found=false, error=\"\").\n Value: \"redis_unavailable\" on Redis errors.","type":"string"},"found":{"type":"boolean"},"generatedAt":{"description":"Unix timestamp in milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"note":{"description":"Set when run_id differs from the returned package's run_id.","type":"string"},"runId":{"type":"string"},"schemaVersion":{"type":"string"},"theaterCount":{"format":"int32","type":"integer"}},"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"},"MarketAlertRow":{"description":"One market-alert type's rolling hit rate beside its base rate.","properties":{"baseHitRate":{"format":"double","type":"number"},"baseN":{"format":"int32","type":"integer"},"hitRate":{"format":"double","type":"number"},"medianLeadTimeMs":{"description":"Median over hits; omitted below 30 hits.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"pairedHitRate":{"description":"Hit rate over the rows whose control scored; compare with base_hit_rate.","format":"double","type":"number"},"scored":{"description":"Alerts resolved HIT or MISS.","format":"int32","type":"integer"},"type":{"type":"string"}},"type":"object"},"MarketAlertScorecard":{"description":"Rolling scorecard of the market-alert ledger.","properties":{"byType":{"items":{"$ref":"#/components/schemas/MarketAlertRow"},"type":"array"},"generatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"methodology":{"type":"string"},"rollingWindowDays":{"format":"int32","type":"integer"},"windowHours":{"format":"int32","type":"integer"}},"type":"object"},"Perspectives":{"properties":{"contrarian":{"type":"string"},"regional":{"type":"string"},"strategic":{"type":"string"}},"type":"object"},"Projections":{"description":"Deprecated (#8967): newly seeded payloads omit it; a payload cached\n before the change may carry it until the next seed-forecasts run.","properties":{"d30":{"format":"double","type":"number"},"d7":{"format":"double","type":"number"},"h24":{"format":"double","type":"number"}},"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"},"ResolutionSpec":{"description":"Resolution spec that makes a forecast scoreable. kind is \"hard\" (resolved by\n comparing metric_key from source_feed to threshold with operator \"\u003e=\", \"\u003c=\"\n or \"crosses\") or \"judged\" (an LLM judge answers question). Other fields apply\n per kind. baseline_value applies only to \"crosses\" specs. A judged spec's\n threshold is absent, never 0.","properties":{"baselineValue":{"format":"double","type":"number"},"deadline":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"kind":{"type":"string"},"metricKey":{"type":"string"},"operator":{"type":"string"},"question":{"type":"string"},"sourceFeed":{"type":"string"},"threshold":{"format":"double","type":"number"},"window":{"type":"string"}},"required":["kind","deadline"],"type":"object"},"ScorecardCalibrationBucket":{"properties":{"brier":{"format":"double","type":"number"},"bucket":{"type":"string"},"count":{"format":"int32","type":"integer"},"maxProbability":{"format":"double","type":"number"},"minProbability":{"format":"double","type":"number"},"predictedMean":{"format":"double","type":"number"},"realizedRate":{"format":"double","type":"number"}},"type":"object"},"ScorecardDomainGroup":{"properties":{"brier":{"format":"double","type":"number"},"domain":{"type":"string"},"logScore":{"format":"double","type":"number"},"resolved":{"format":"int32","type":"integer"},"scored":{"format":"int32","type":"integer"},"void":{"format":"int32","type":"integer"},"voidRate":{"format":"double","type":"number"}},"type":"object"},"ScorecardFamilyOutcome":{"properties":{"forecastId":{"type":"string"},"outcome":{"type":"string"},"voidReason":{"type":"string"}},"type":"object"},"ScorecardFunnel":{"description":"Matured means past deadline or resolved.","properties":{"immature":{"format":"int32","type":"integer"},"matured":{"format":"int32","type":"integer"},"maturityUnknown":{"format":"int32","type":"integer"},"pendingHardMatured":{"format":"int32","type":"integer"},"pendingJudgeMatured":{"format":"int32","type":"integer"},"resolved":{"format":"int32","type":"integer"},"resolvedOfMatured":{"$ref":"#/components/schemas/ScorecardProportion"},"scored":{"format":"int32","type":"integer"},"scoredOfMatured":{"$ref":"#/components/schemas/ScorecardProportion"}},"type":"object"},"ScorecardGenerationOriginGroup":{"properties":{"brier":{"format":"double","type":"number"},"generationOrigin":{"type":"string"},"logScore":{"format":"double","type":"number"},"resolved":{"format":"int32","type":"integer"},"scored":{"format":"int32","type":"integer"},"void":{"format":"int32","type":"integer"},"voidRate":{"format":"double","type":"number"}},"type":"object"},"ScorecardInterval":{"description":"Bootstrap interval on a mean Brier score.","properties":{"ci95":{"items":{"description":"[low, high] at 95%.","format":"double","type":"number"},"type":"array"},"count":{"format":"int32","type":"integer"},"insufficientSample":{"description":"True below the family minimums.","type":"boolean"},"mean":{"format":"double","type":"number"}},"type":"object"},"ScorecardMarketSkill":{"properties":{"brierDelta":{"format":"double","type":"number"},"count":{"format":"int32","type":"integer"},"forecastBrier":{"format":"double","type":"number"},"marketBrier":{"format":"double","type":"number"}},"type":"object"},"ScorecardProportion":{"description":"successes of count, with a Wilson interval.","properties":{"ci95":{"items":{"description":"[low, high] at 95%.","format":"double","type":"number"},"type":"array"},"count":{"format":"int32","type":"integer"},"rate":{"format":"double","type":"number"},"successes":{"format":"int32","type":"integer"}},"type":"object"},"ScorecardPublishedDomain":{"properties":{"brier":{"format":"double","type":"number"},"bss":{"format":"double","type":"number"},"count":{"format":"int32","type":"integer"},"domain":{"type":"string"},"yesCount":{"format":"int32","type":"integer"}},"type":"object"},"ScorecardReceipt":{"properties":{"citationTitle":{"type":"string"},"citationUrl":{"type":"string"},"forecastAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"observedValue":{"format":"double","type":"number"},"outcome":{"type":"string"},"probability":{"format":"double","type":"number"},"question":{"type":"string"},"resolvedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"sourceFeed":{"type":"string"},"voidReason":{"type":"string"}},"type":"object"},"ScorecardSkill":{"description":"Headline Brier/log score over scored entries that are neither synthetic\n backfill nor unpromoted shadow streams; count 0 with excluded_scored \u003e 0\n means every scored entry was excluded.","properties":{"brier":{"format":"double","type":"number"},"bssCi95":{"items":{"format":"double","type":"number"},"type":"array"},"count":{"format":"int32","type":"integer"},"excludedOrigins":{"items":{"type":"string"},"type":"array"},"excludedScored":{"format":"int32","type":"integer"},"logScore":{"format":"double","type":"number"},"yesCount":{"format":"int32","type":"integer"}},"type":"object"},"ScorecardSummary":{"properties":{"brier":{"format":"double","type":"number"},"count":{"format":"int32","type":"integer"},"logScore":{"format":"double","type":"number"}},"type":"object"},"ScorecardTotals":{"properties":{"entries":{"format":"int32","type":"integer"},"pending":{"format":"int32","type":"integer"},"pendingJudge":{"format":"int32","type":"integer"},"publicationCoverage":{"deprecated":true,"format":"double","type":"number"},"resolved":{"format":"int32","type":"integer"},"scored":{"format":"int32","type":"integer"},"void":{"format":"int32","type":"integer"},"voidRate":{"format":"double","type":"number"}},"type":"object"},"ScorecardUncertainty":{"properties":{"method":{"type":"string"},"overallBrier":{"$ref":"#/components/schemas/ScorecardInterval"},"skillBrier":{"$ref":"#/components/schemas/ScorecardInterval"}},"type":"object"},"ScorecardUnderAudit":{"properties":{"issue":{"format":"int32","type":"integer"},"reason":{"type":"string"},"since":{"type":"string"}},"type":"object"},"TriggerSimulationRequest":{"description":"TriggerSimulationRequest enqueues a run for the current simulation package.","properties":{"clientVersion":{"description":"Optional client version, such as \"mcp-client/0.2\". Logged, never stored.","type":"string"}},"type":"object"},"TriggerSimulationResponse":{"description":"TriggerSimulationResponse is the HTTP 200 result of an enqueue attempt.\n Errors return a non-200 status instead.","properties":{"pkgFingerprint":{"description":"Opaque fingerprint of the package key; it changes when the key changes.\n Empty when reason='no_package'.","type":"string"},"queued":{"description":"True when the task was newly enqueued; false on idempotency hit or\n no_package.","type":"boolean"},"reason":{"description":"'' when queued, 'no_package' when no package exists, or 'already-handled'\n when this cycle's run is already queued or done.","type":"string"},"runId":{"description":"Server-derived runId from SIMULATION_PACKAGE_LATEST_KEY. Empty\n string when reason='no_package' (no package pointer was available).","type":"string"}},"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"},"BearerAuth":{"description":"Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer \u003ctoken\u003e.","scheme":"bearer","type":"http"},"WorldMonitorKey":{"description":"User-issued WorldMonitor API key.","in":"header","name":"X-WorldMonitor-Key","type":"apiKey"}}},"info":{"title":"ForecastService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/forecast/v1/get-forecast-scorecard":{"get":{"description":"GetForecastScorecard returns the latest forecast resolution scorecard; degraded distinguishes a backend outage from a healthy empty scorecard.","operationId":"GetForecastScorecard","parameters":[{"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":{"byDomain":[{"brier":1.5,"domain":"example","logScore":42.5,"resolved":1,"scored":42}],"byGenerationOrigin":[{"brier":1.5,"generationOrigin":"example","logScore":42.5,"resolved":1,"scored":42}],"calibration":[{"brier":1.5,"bucket":"example","count":1,"maxProbability":0.62,"minProbability":0.62}],"degraded":true,"error":"example"},"schema":{"$ref":"#/components/schemas/GetForecastScorecardResponse"}}},"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":"GetForecastScorecard","tags":["ForecastService"]}},"/api/forecast/v1/get-forecasts":{"get":{"description":"GetForecasts returns the latest generated probabilistic forecasts; the degraded flag distinguishes a backend outage from a healthy empty set.","operationId":"GetForecasts","parameters":[{"description":"Forecast domain to retrieve, such as geopolitics, markets, or climate.","example":"conflict","in":"query","name":"domain","required":false,"schema":{"enum":["conflict","market","supply_chain","political","military","cyber","infrastructure"],"type":"string"}},{"description":"Optional geographic or thematic region filter for forecasts.","example":"example","in":"query","name":"region","required":false,"schema":{"type":"string"}},{"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":{"degraded":true,"error":"example","forecasts":[{"calibration":{"drift":1.5,"internalProbability":0.62,"marketBlendedProbability":0.62,"marketPrice":75.25,"marketTitle":"example"},"cascades":[{"domain":"example","effect":"example","probability":0.62}],"caseFile":{"actorLenses":["example"],"actors":[{"category":"cs.AI","constraints":["example"],"id":"example-id","influenceScore":42.5,"likelyActions":["example"]}],"baseCase":"example","branches":[{"kind":"example","outcome":"example","projectedProbability":0.62,"rounds":[{}],"summary":"Example WorldMonitor observation."}],"changeItems":["example"]},"confidence":0.82,"createdAt":1717200000000}],"generatedAt":1717200000000,"stale":true},"schema":{"$ref":"#/components/schemas/GetForecastsResponse"}}},"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":"GetForecasts","tags":["ForecastService"]}},"/api/forecast/v1/get-simulation-outcome":{"get":{"description":"GetSimulationOutcome returns the latest forecast simulation outcome, refreshed\n about hourly. The response note is set when a supplied runId does not match.","operationId":"GetSimulationOutcome","parameters":[{"description":"Optional run ID (epoch ms, hyphen, 1-64 char suffix; max 128). Returns that\n run's outcome within 24h retention, processing=true while it is queued, or\n the latest outcome with a note. Empty returns the latest outcome.","example":"1789387200000-abc123","in":"query","name":"runId","required":false,"schema":{"example":"1789387200000-abc123","maxLength":128,"pattern":"^([0-9]{13,}-[A-Za-z0-9-]{1,64})?$","type":"string"}},{"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":{"allTheatersFailed":true,"completionStatus":"example","eligibleTheaterCount":1,"error":"example","failedTheaterCount":1},"schema":{"$ref":"#/components/schemas/GetSimulationOutcomeResponse"}}},"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":"GetSimulationOutcome","tags":["ForecastService"]}},"/api/forecast/v1/get-simulation-package":{"get":{"description":"GetSimulationPackage returns the latest forecast simulation package; the response note is populated when a supplied runId does not match the returned package.","operationId":"GetSimulationPackage","parameters":[{"description":"Optional run identifier. It does not select a package yet: the latest is\n always returned, and note says when it differs.","example":"example-id","in":"query","name":"runId","required":false,"schema":{"type":"string"}},{"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":{"error":"example","found":true,"generatedAt":1717200000000,"note":"example","runId":"example-id"},"schema":{"$ref":"#/components/schemas/GetSimulationPackageResponse"}}},"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":"GetSimulationPackage","tags":["ForecastService"]}},"/api/forecast/v1/trigger-simulation":{"post":{"description":"TriggerSimulation enqueues a simulation run for the current package outside\n the hourly cycle. PRO-gated. Poll GetSimulationOutcome with the returned runId. Requires entitlement tier \u003e= 1.","operationId":"TriggerSimulation","parameters":[{"description":"Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.","example":"4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"pattern":"^[\\x21-\\x7E]{1,255}$","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"clientVersion":"example"},"schema":{"$ref":"#/components/schemas/TriggerSimulationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"pkgFingerprint":"example","queued":true,"reason":"example","runId":"example-id"},"schema":{"$ref":"#/components/schemas/TriggerSimulationResponse"}}},"description":"Successful response","headers":{"Idempotency-Key":{"description":"The idempotency key echoed from the request. Present only when the client opted into idempotency.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency.","schema":{"type":"boolean"}}}},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"type":"object"},{"$ref":"#/components/schemas/InvalidRequestBodyError"}]}}},"description":"Validation error, invalid Idempotency-Key header, or malformed JSON request body"},"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":"PRO entitlement access denied.","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"}}}},"409":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"type":"object"}}},"description":"A request with this Idempotency-Key is still being processed","headers":{"Idempotency-Key":{"description":"The idempotency key supplied by the client.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying the in-flight request.","schema":{"type":"string"}}}},"422":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"type":"object"}}},"description":"The Idempotency-Key was already used with a different request body","headers":{"Idempotency-Key":{"description":"The idempotency key supplied by the client.","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."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"TriggerSimulation","tags":["ForecastService"]}}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]}],"servers":[{"url":"https://api.worldmonitor.app"}]}