{"openapi":"3.1.0","info":{"title":"PolyBridge API","description":"Public OpenAPI schema for the PolyBridge Search and Forecast REST APIs.","version":"0.1.0"},"paths":{"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/forecast":{"post":{"summary":"Forecast","operationId":"forecast_v1_forecast_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicForecastRequest"}}},"required":true},"responses":{"200":{"description":"Successful public Forecast response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicForecastResponse"}}}},"422":{"description":"Forecast request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"403":{"description":"Bearer API key is not authorized for Forecast access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"413":{"description":"Forecast request body exceeded the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"429":{"description":"Forecast request exceeded the applicable rate limit or concurrency budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds a client should wait before retrying the request.","schema":{"type":"string"}}}},"431":{"description":"Forecast request headers exceeded the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"502":{"description":"Forecast generation failed after an upstream or internal processing error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"Forecast timed out or the service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds a client should wait before retrying the request.","schema":{"type":"string"}}}}},"security":[{"bearerAuth":[]}],"description":"Requires a bearer Forecast API key with the explicit forecast:read scope. Anonymous access is not supported. Search-only keys and legacy broad keys without explicit forecast:read access return 403. This route returns the public-safe Forecast response shape and public-safe Oracle-port metadata only.","x-required-scopes":["forecast:read"],"parameters":[{"name":"X-Polybridge-Attribution-Code","in":"header","required":false,"schema":{"type":"string"},"description":"Optional attribution code for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."},{"name":"X-Polybridge-Referrer","in":"header","required":false,"schema":{"type":"string"},"description":"Optional referrer URL for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."},{"name":"X-Polybridge-Channel","in":"header","required":false,"schema":{"type":"string"},"description":"Optional channel identifier for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."},{"name":"X-Polybridge-Tool","in":"header","required":false,"schema":{"type":"string"},"description":"Optional tool identifier for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."},{"name":"X-Polybridge-Client","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client identifier for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."},{"name":"X-Polybridge-Client-Version","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client version for integration or channel debugging. Optional self-reported integration hint. Do not send tokens, credentials, emails, hostnames, local usernames, or private machine data."}]}},"/v1/search":{"post":{"summary":"Search","operationId":"search_v1_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful public Search response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSearchResponse"}}}},"422":{"description":"Search request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"401":{"description":"Invalid or unauthorized bearer token. Requests with an invalid bearer token do not fall back to anonymous access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"429":{"description":"Search request exceeded the applicable rate limit or concurrency budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds a client should wait before retrying the request.","schema":{"type":"string"}}}},"503":{"description":"Search request timed out or the service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds a client should wait before retrying the request.","schema":{"type":"string"}}}}},"security":[{},{"bearerAuth":[]}],"description":"Anonymous access is allowed. Requests may omit Authorization to use the anonymous tier, or send a bearer Search API key for higher limits. Invalid bearer tokens return 401 and do not fall back to anonymous access. Anonymous callers are limited to 1 request/second, must use top_k_per_dimension <= 20, and may request at most 4 dimensions. Use filters.status=\"active\" for forward-looking workflows that should exclude closed or resolved markets."}}},"components":{"schemas":{"PublicCausalGraphView":{"additionalProperties":false,"properties":{"nodes":{"description":"Nodes in the public causal graph view.","items":{"$ref":"#/components/schemas/PublicGraphNode"},"title":"Nodes","type":"array"},"edges":{"description":"Edges in the public causal graph view.","items":{"$ref":"#/components/schemas/PublicGraphEdge"},"title":"Edges","type":"array"}},"required":["nodes","edges"],"title":"PublicCausalGraphView","type":"object"},"PublicConfidenceInterval":{"additionalProperties":false,"properties":{"lower":{"description":"Lower bound of the forecast confidence interval.","title":"Lower","type":"number"},"upper":{"description":"Upper bound of the forecast confidence interval.","title":"Upper","type":"number"}},"required":["lower","upper"],"title":"PublicConfidenceInterval","type":"object"},"PublicErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"$ref":"#/components/schemas/PublicValidationErrorDetail"},"type":"array"}],"description":"Human-readable error detail or structured validation issues.","title":"Detail"}},"required":["detail"],"title":"PublicErrorResponse","type":"object"},"PublicForecastMetadata":{"additionalProperties":false,"properties":{"oracle_port":{"anyOf":[{"$ref":"#/components/schemas/PublicOraclePortMetadata"},{"type":"null"}],"default":null,"description":"Public-safe Oracle-port metadata."}},"title":"PublicForecastMetadata","type":"object"},"PublicForecastRequest":{"additionalProperties":false,"properties":{"question":{"description":"Forecast question. Blank or whitespace-only values are rejected.","maxLength":500,"minLength":1,"title":"Question","type":"string"},"include_graph":{"default":true,"description":"When true, include a public causal graph view when available.","title":"Include Graph","type":"boolean"}},"required":["question"],"title":"PublicForecastRequest","type":"object"},"PublicForecastResponse":{"additionalProperties":false,"properties":{"request_id":{"description":"Server-generated identifier for this forecast request.","title":"Request Id","type":"string"},"question":{"description":"Original question echoed back by the API.","title":"Question","type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Forecast probability estimate, or null when no public estimate is available.","title":"Probability"},"confidence":{"description":"Normalized confidence score for the forecast output.","title":"Confidence","type":"number"},"confidence_interval":{"anyOf":[{"$ref":"#/components/schemas/PublicConfidenceInterval"},{"type":"null"}],"default":null,"description":"Forecast confidence interval, when available."},"reasoning":{"description":"Public natural-language explanation for the forecast.","title":"Reasoning","type":"string"},"engine_type":{"const":"oracle_port","description":"Forecast engine label. Current production public Forecast uses oracle_port.","title":"Engine Type","type":"string"},"causal_graph":{"anyOf":[{"$ref":"#/components/schemas/PublicCausalGraphView"},{"type":"null"}],"default":null,"description":"Public causal graph view, when requested and available."},"markets_used":{"description":"Source markets used as evidence for the forecast.","items":{"$ref":"#/components/schemas/PublicMarketSummary"},"title":"Markets Used","type":"array"},"distribution":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"description":"Optional probability distribution output, when available.","title":"Distribution"},"latency_ms":{"description":"End-to-end forecast latency in milliseconds.","title":"Latency Ms","type":"integer"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"User-facing error or validation message when no probability is produced.","title":"Error"},"metadata":{"$ref":"#/components/schemas/PublicForecastMetadata","description":"Curated public-safe Forecast metadata."}},"required":["request_id","question","confidence","reasoning","engine_type","markets_used","latency_ms","metadata"],"title":"PublicForecastResponse","type":"object"},"PublicGraphEdge":{"additionalProperties":false,"properties":{"source":{"description":"Source graph node identifier.","title":"Source","type":"string"},"target":{"description":"Target graph node identifier.","title":"Target","type":"string"},"relationship":{"description":"Human-readable relationship label.","title":"Relationship","type":"string"},"strength":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Relationship strength score, when available.","title":"Strength"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional explanation for the relationship.","title":"Description"}},"required":["source","target","relationship"],"title":"PublicGraphEdge","type":"object"},"PublicGraphNode":{"additionalProperties":false,"properties":{"id":{"description":"Stable graph node identifier.","title":"Id","type":"string"},"label":{"description":"Human-readable graph node label.","title":"Label","type":"string"},"markets":{"description":"Markets associated with this graph node.","items":{"$ref":"#/components/schemas/PublicMarketSummary"},"title":"Markets","type":"array"},"current_probability":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Current probability estimate for the node, when available.","title":"Current Probability"}},"required":["id","label","markets"],"title":"PublicGraphNode","type":"object"},"PublicMarketSummary":{"additionalProperties":false,"properties":{"id":{"description":"Stable PolyBridge market identifier.","title":"Id","type":"string"},"question":{"description":"Market question shown to end users.","title":"Question","type":"string"},"platform":{"description":"Prediction market platform name.","enum":["polymarket","kalshi"],"title":"Platform","type":"string"},"current_prices":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"description":"Current market prices by outcome label, when available.","title":"Current Prices"},"platform_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Direct URL for the market on the source platform, when available.","title":"Platform Url"}},"required":["id","question","platform"],"title":"PublicMarketSummary","type":"object"},"PublicOraclePortMetadata":{"additionalProperties":false,"properties":{"original_question":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Original question supplied by the caller.","title":"Original Question"},"effective_question":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Question used for Forecast execution after any normalization.","title":"Effective Question"},"normalized_question":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Normalized question text, when normalization was applied.","title":"Normalized Question"},"rewrite_applied":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the question was rewritten before execution.","title":"Rewrite Applied"},"normalization_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Human-readable reason for normalization, when applicable.","title":"Normalization Reason"},"search_query_used":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Search query used to gather supporting markets, when applicable.","title":"Search Query Used"},"insufficient_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the forecast completed with insufficient data.","title":"Insufficient Data"},"fallbacks_applied":{"description":"Public-safe fallback markers applied during Forecast execution.","items":{"type":"string"},"title":"Fallbacks Applied","type":"array"},"relevance_filter_summary":{"anyOf":[{"$ref":"#/components/schemas/PublicRelevanceFilterSummary"},{"type":"null"}],"default":null,"description":"Public-safe summary of the selected evidence markets."}},"title":"PublicOraclePortMetadata","type":"object"},"PublicRelevanceFilterSummary":{"additionalProperties":false,"properties":{"selected_direct_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Number of direct evidence markets selected for synthesis.","title":"Selected Direct Count"},"selected_proxy_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Number of proxy evidence markets selected for synthesis.","title":"Selected Proxy Count"},"selected_weak_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Number of weak evidence markets selected for synthesis.","title":"Selected Weak Count"},"selected_evidence_profile":{"anyOf":[{"enum":["direct_mixed","direct_only","proxy_only","weak_only","none"],"type":"string"},{"type":"null"}],"default":null,"description":"High-level evidence profile of the selected markets.","title":"Selected Evidence Profile"},"selected_direct_evidence_missing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether direct evidence was unavailable in the selected market set.","title":"Selected Direct Evidence Missing"},"selected_proxy_dominant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether proxy evidence dominated the selected market set.","title":"Selected Proxy Dominant"}},"title":"PublicRelevanceFilterSummary","type":"object"},"PublicSearchFilters":{"properties":{"status":{"anyOf":[{"enum":["active","closed","resolved"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional market status filter. Use status=\"active\" for forward-looking workflows to exclude closed or resolved markets.","title":"Status"}},"title":"PublicSearchFilters","type":"object"},"PublicSearchRequest":{"properties":{"query":{"description":"Market search query string.","title":"Query","type":"string"},"dimensions":{"description":"Search dimensions to query. Defaults to all supported dimensions. Anonymous callers may request up to 4.","items":{"enum":["direct","upstream","downstream","correlated"],"type":"string"},"minItems":1,"title":"Dimensions","type":"array"},"top_k_per_dimension":{"default":20,"description":"Maximum number of results to return per dimension. Anonymous callers must use a value of 20 or less.","minimum":1,"title":"Top K Per Dimension","type":"integer"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PublicSearchFilters"},{"type":"null"}],"default":null,"description":"Optional public search filters."}},"required":["query"],"title":"PublicSearchRequest","type":"object"},"PublicSearchResponse":{"properties":{"request_id":{"description":"Server-generated identifier for this search request.","title":"Request Id","type":"string"},"query":{"description":"Original query string echoed back by the API.","title":"Query","type":"string"},"results":{"additionalProperties":{"items":{"$ref":"#/components/schemas/PublicSearchResult"},"type":"array"},"description":"Ordered public Search results grouped by dimension.","title":"Results","type":"object"},"total_markets":{"description":"Total number of public Search results returned across all dimensions in this response after applied filters and public shaping.","title":"Total Markets","type":"integer"},"latency_ms":{"description":"End-to-end search latency in milliseconds.","title":"Latency Ms","type":"integer"}},"required":["request_id","query","results","total_markets","latency_ms"],"title":"PublicSearchResponse","type":"object"},"PublicSearchResult":{"properties":{"id":{"description":"Stable PolyBridge market identifier.","title":"Id","type":"string"},"platform":{"description":"Prediction market platform name.","title":"Platform","type":"string"},"question":{"description":"Market question shown to end users.","title":"Question","type":"string"},"outcomes":{"description":"Ordered market outcome labels.","items":{"type":"string"},"title":"Outcomes","type":"array"},"status":{"description":"Current market lifecycle status.","enum":["active","closed","resolved"],"title":"Status","type":"string"},"platform_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Direct URL for the market on the source platform, when available.","title":"Platform Url"},"score":{"description":"Search relevance score used for ranking. This is not a probability and is most useful when comparing results within the same response and dimension.","title":"Score","type":"number"},"dimension":{"description":"Search dimension that produced this result.","title":"Dimension","type":"string"}},"required":["id","platform","question","outcomes","status","score","dimension"],"title":"PublicSearchResult","type":"object"},"PublicValidationErrorDetail":{"properties":{"loc":{"description":"Location of the validation error.","items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Loc","type":"array"},"msg":{"description":"Validation failure message.","title":"Msg","type":"string"},"type":{"description":"Machine-readable validation error type.","title":"Type","type":"string"}},"required":["loc","msg","type"],"title":"PublicValidationErrorDetail","type":"object"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Bearer token for authenticated PolyBridge API access. Search requests may omit Authorization to use anonymous access. Forecast requests require a bearer API key."}}}}