{"openapi":"3.1.0","info":{"title":"Context Relay","version":"0.3.0","description":"Paid, deterministic retrieval of compact, citation-verifiable context from public HTML pages."},"servers":[{"url":"https://context-relay.contextrelay.workers.dev"}],"paths":{"/api/v1/capabilities":{"get":{"operationId":"getContextRelayCapabilities","responses":{"200":{"description":"Canonical capabilities"}}}},"/api/v1/health":{"get":{"operationId":"getContextRelayHealth","responses":{"200":{"description":"Non-secret readiness"}}}},"/api/v1/context/quote":{"post":{"operationId":"quoteContext","summary":"Get a free route, value, price, latency, and policy quote.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":4096,"description":"Public HTTP or HTTPS page to retrieve."},"question":{"type":"string","maxLength":2000,"description":"Optional task or question used to rank relevant passages."},"max_tokens":{"type":"integer","minimum":250,"maximum":12000,"default":4000},"max_price_usd":{"type":"number","minimum":0,"description":"Abort before retrieval if the fixed service price exceeds this amount."},"freshness_seconds":{"type":"integer","minimum":60,"maximum":86400,"default":3600}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","required":["schema_version","quote_id","canonical_url","cache_status","route","quoted_price_usd","currency","network","cost_class","economics","within_budget","supported","estimated_latency_ms","features","limitations","expires_at"],"properties":{"schema_version":{"const":"context-quote.v1"},"quote_id":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"cache_status":{"enum":["hit","miss"]},"route":{"enum":["cache","public_html_direct"]},"quoted_price_usd":{"type":"number"},"currency":{"const":"USDC"},"network":{"type":"string"},"cost_class":{"enum":["cached","fresh_static"]},"economics":{"type":"object"},"within_budget":{"type":"boolean"},"supported":{"type":"boolean"},"estimated_latency_ms":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["schema_version","request_id","delivery_status","error"],"properties":{"schema_version":{"const":"context-error.v1"},"request_id":{"type":"string"},"delivery_status":{"const":"failed"},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}},"/api/v1/context":{"post":{"operationId":"retrieveContext","summary":"Retrieve compact context with exact evidence and a verifiable receipt.","description":"Requires an x402 payment. Settlement happens only after a response below HTTP 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":4096,"description":"Public HTTP or HTTPS page to retrieve."},"question":{"type":"string","maxLength":2000,"description":"Optional task or question used to rank relevant passages."},"max_tokens":{"type":"integer","minimum":250,"maximum":12000,"default":4000},"max_price_usd":{"type":"number","minimum":0,"description":"Abort before retrieval if the fixed service price exceeds this amount."},"freshness_seconds":{"type":"integer","minimum":60,"maximum":86400,"default":3600}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Context receipt; settlement proof is in PAYMENT-RESPONSE","content":{"application/json":{"schema":{"type":"object","required":["schema_version","receipt_id","context_id","source","transformation","context","delivery","safety"],"properties":{"schema_version":{"const":"context-receipt.v1"},"receipt_id":{"type":"string"},"context_id":{"type":"string"},"source":{"type":"object","required":["requested_url","canonical_url","final_url","title","fetched_at","content_type","content_sha256"],"properties":{"requested_url":{"type":"string","format":"uri"},"canonical_url":{"type":"string","format":"uri"},"final_url":{"type":"string","format":"uri"},"title":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"content_type":{"type":"string"},"content_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"additionalProperties":false},"transformation":{"type":"object","required":["pipeline_version","method","question","max_tokens","model_used"],"properties":{"pipeline_version":{"const":"html-deterministic.v1"},"method":{"const":"deterministic_extract"},"question":{"type":["string","null"]},"max_tokens":{"type":"integer","minimum":250,"maximum":12000},"model_used":{"const":false}},"additionalProperties":false},"context":{"type":"object","required":["markdown","citations","raw_token_estimate","returned_token_estimate","estimated_tokens_saved","token_estimate_method"],"properties":{"markdown":{"type":"string"},"citations":{"type":"array","minItems":1,"items":{"type":"object","required":["id","locator","excerpt","excerpt_sha256"],"properties":{"id":{"type":"string"},"locator":{"type":"string"},"excerpt":{"type":"string"},"excerpt_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"additionalProperties":false}},"raw_token_estimate":{"type":"integer","minimum":1},"returned_token_estimate":{"type":"integer","minimum":1},"estimated_tokens_saved":{"type":"integer","minimum":0},"token_estimate_method":{"const":"characters_divided_by_4"}},"additionalProperties":false},"delivery":{"type":"object","required":["status","route","cache_status","price_usd","currency","network","cost_class","economics","latency_ms","generated_at","payment"],"properties":{"status":{"const":"delivered"},"route":{"enum":["cache","public_html_direct"]},"cache_status":{"enum":["hit","miss"]},"price_usd":{"type":"number","minimum":0},"currency":{"const":"USDC"},"network":{"type":"string"},"cost_class":{"enum":["cached","fresh_static"]},"economics":{"type":"object","required":["estimate_basis","estimated_variable_cost_usd","estimated_gross_profit_usd","estimated_gross_margin"],"properties":{"estimate_basis":{"const":"configured_route_estimate"},"estimated_variable_cost_usd":{"type":"number","minimum":0},"estimated_gross_profit_usd":{"type":"number"},"estimated_gross_margin":{"type":"number"}},"additionalProperties":false},"latency_ms":{"type":"integer","minimum":0},"generated_at":{"type":"string","format":"date-time"},"payment":{"type":"object","required":["protocol","verification_status","settlement_status","settlement_receipt_header","failed_delivery_charge_policy"],"properties":{"protocol":{"const":"x402"},"verification_status":{"enum":["verified","internal_unverified"]},"settlement_status":{"enum":["reported_in_response_header","reported_in_mcp_meta","not_applicable"]},"settlement_receipt_header":{"enum":["PAYMENT-RESPONSE","x402/payment-response",null]},"failed_delivery_charge_policy":{"const":"not_settled_when_handler_status_is_400_or_higher"}},"additionalProperties":false}},"additionalProperties":false},"safety":{"type":"object","required":["public_source_only","shared_cache_eligible","source_directives","robots_policy","prompt_injection_signals"],"properties":{"public_source_only":{"const":true},"shared_cache_eligible":{"type":"boolean"},"source_directives":{"type":"array","items":{"type":"string"}},"robots_policy":{"enum":["allowed","not_present","unavailable_4xx"]},"prompt_injection_signals":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}}},"402":{"description":"x402 payment required, rejected, or settlement failed"},"403":{"description":"Source policy rejection","content":{"application/json":{"schema":{"type":"object","required":["schema_version","request_id","delivery_status","error"],"properties":{"schema_version":{"const":"context-error.v1"},"request_id":{"type":"string"},"delivery_status":{"const":"failed"},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"422":{"description":"Page could not be extracted","content":{"application/json":{"schema":{"type":"object","required":["schema_version","request_id","delivery_status","error"],"properties":{"schema_version":{"const":"context-error.v1"},"request_id":{"type":"string"},"delivery_status":{"const":"failed"},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"502":{"description":"Upstream failure","content":{"application/json":{"schema":{"type":"object","required":["schema_version","request_id","delivery_status","error"],"properties":{"schema_version":{"const":"context-error.v1"},"request_id":{"type":"string"},"delivery_status":{"const":"failed"},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}}}}