Agent Preflight Api API

{"openapi":"3.1.0","info":{"title":"Agent Preflight","version":"0.3.0","description":"V0.3: V0.1 validates a proposed HTTP body against JSON Schema. POST /v0.2/preflight/tool-call returns allow|block|reuse|defer|advise for a budgeted tool call without executing it. Production charges $0.002 USDC per HTTP POST on Base mainnet (eip155:8453) via x402 when payment env is enabled. MCP and /check-request stay unpaid."},"servers":[{"url":"https://api.agent-preflight.com","description":"Production API"},{"url":"/","description":"This Worker"}],"paths":{"/check-request":{"post":{"operationId":"checkRequest","summary":"Validate a proposed HTTP request body","description":"Applies the supplied JSON Schema to request.body. Never sends the proposed HTTP request. Unsupported schema keywords are rejected rather than treated as warnings. When economics is supplied, the 200 body also contains proceed/abort expected-cost advice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request","schema"],"additionalProperties":false,"properties":{"request":{"type":"object","required":["method","url"],"properties":{"method":{"type":"string","examples":["POST"]},"url":{"type":"string","description":"Absolute http(s) URL. Never fetched."},"headers":{"type":"object","additionalProperties":{"type":"string"}},"query":{"type":"object","additionalProperties":true},"body":{}}},"schema":{"type":"object","description":"JSON Schema applied only to request.body. V0.1 supports type, required, properties, items, enum, const, minimum, maximum, minLength, maxLength, pattern, and additionalProperties. Unsupported keywords are rejected. Maximum schema size is 32768 bytes.","additionalProperties":true},"economics":{"type":"object","required":["downstreamCostUsd","billsOnInvalidRequest","retryCostUsd"],"additionalProperties":false,"properties":{"downstreamCostUsd":{"type":"number","minimum":0,"description":"USD cost of the target API attempt or success"},"billsOnInvalidRequest":{"type":"boolean","description":"True when the target API charges or consumes quota on 4xx"},"retryCostUsd":{"type":"number","minimum":0,"description":"USD model/tool-turn cost of one failed attempt"},"priorInvalidProbability":{"type":"number","minimum":0,"maximum":1,"description":"Prior probability the payload is doomed. Default 0.25"},"preflightPriceUsd":{"type":"number","minimum":0,"description":"Price of this check. Default 0.002"},"budgetRemainingUsd":{"type":"number","minimum":0,"description":"Remaining agent budget"}},"description":"Optional V0.2 cost context. Omit for V0.1 validation-only output."}}},"example":{"request":{"method":"POST","url":"https://example.com/api/users","headers":{"content-type":"application/json"},"query":{},"body":{"name":"Alice"}},"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}}},"responses":{"200":{"description":"Check completed. valid=false means the proposed request or schema failed validation.","content":{"application/json":{"schema":{"type":"object","required":["valid","errors","warnings","requestHash"],"additionalProperties":false,"properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}},"requestHash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 hex of the normalized request + schema"},"economics":{"type":"object","required":["decision","reason","preflightPriceUsd","wasteIfSentUsd","realizedNetUsd","worthCheckingAPriori","aPrioriExpectedWasteUsd","aPrioriExpectedNetUsd"],"additionalProperties":false,"properties":{"decision":{"type":"string","enum":["proceed","abort"]},"reason":{"type":"string","enum":["valid","invalid_doomed_request"]},"preflightPriceUsd":{"type":"number"},"wasteIfSentUsd":{"type":"number"},"realizedNetUsd":{"type":"number"},"worthCheckingAPriori":{"type":"boolean"},"aPrioriExpectedWasteUsd":{"type":"number"},"aPrioriExpectedNetUsd":{"type":"number"}}}}}}}},"400":{"description":"Malformed JSON, invalid input, or unsupported/malformed schema.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}},"404":{"description":"Unknown path.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}},"413":{"description":"HTTP body larger than 65536 bytes.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}}}}},"/v0.2/preflight/tool-call":{"post":{"operationId":"preflightToolCall","summary":"Decide whether to execute a metered tool call","description":"Generic search:web_search and browse:fetch proposals only; never executes the destination tool. Supply budget remaining after accounting for the consultation fee. Production paid HTTP charges $0.002 USDC per settled POST, including allow/advise. estimated.priceChargedUsd and billable are legacy modeled economics, not settlement receipts. MCP remains unpaid. See https://agent-preflight.com/docs for defaults, history and limitations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["runId","stepId","tool","budget"],"additionalProperties":false,"description":"Pre-execution tool-call decision input. This endpoint evaluates the proposed tool call and does not execute the external tool.","properties":{"runId":{"type":"string","minLength":1,"description":"Caller-scoped run identifier"},"stepId":{"type":"string","minLength":1,"description":"Caller-scoped step identifier within the run"},"tool":{"type":"object","required":["provider","operation","request","estimatedExternalCostUsd"],"additionalProperties":false,"properties":{"provider":{"type":"string","minLength":1,"description":"Tool provider. Supported: search, browse"},"operation":{"type":"string","minLength":1,"description":"Tool operation. Supported: search:web_search, browse:fetch"},"request":{"type":"object","description":"Provider-specific payload. search/web_search requires query (string 1..500) and optional max_results (1..10). browse/fetch requires url (http/https).","additionalProperties":true,"properties":{"query":{"type":"string","minLength":1,"maxLength":500},"max_results":{"type":"integer","minimum":1,"maximum":10},"url":{"type":"string","minLength":1}}},"estimatedExternalCostUsd":{"type":"number","minimum":0,"description":"Estimated USD cost of the external tool call"},"estimatedModelCostUsd":{"type":"number","minimum":0,"description":"Optional estimated USD model cost for this step"}}},"budget":{"type":"object","required":["remainingUsd"],"additionalProperties":false,"properties":{"remainingUsd":{"type":"number","minimum":0},"reservedUsd":{"type":"number","minimum":0},"maxToolCallsRemaining":{"type":"integer","minimum":0}}},"task":{"type":"object","required":["goalHash"],"additionalProperties":false,"properties":{"goalHash":{"type":"string","description":"Opaque goal correlation token"}}},"history":{"type":"array","description":"At most 100 caller-owned prior outcomes; reuse requires explicit permission, positive freshness TTL and matching nonempty goal hashes.","maxItems":100,"items":{"type":"object","required":["toolCallId","fingerprint","outcome","ageSeconds"],"additionalProperties":false,"properties":{"toolCallId":{"type":"string"},"fingerprint":{"type":"string"},"outcome":{"type":"string","enum":["success","terminal_failure","transient_failure"]},"resultReference":{"type":"string"},"ageSeconds":{"type":"number","minimum":0},"goalHash":{"type":"string"}}}},"capabilities":{"type":"object","additionalProperties":false,"properties":{"canReusePriorResult":{"type":"boolean"},"canReduceScope":{"type":"boolean"}}},"freshnessTtlSeconds":{"type":"number","minimum":0,"maximum":1000000000,"description":"Explicit positive TTL required for reuse. Omitted or zero disables reuse."},"retryCap":{"type":"integer","minimum":1,"default":1},"preflightPriceUsd":{"type":"number","minimum":0,"default":0.002,"description":"Modeled actionable fee only; cannot change the actual HTTP settlement price."}}},"example":{"runId":"settlement-check-01","stepId":"paid-call-01","tool":{"provider":"search","operation":"web_search","request":{"query":"Acme Corp Series B funding","max_results":5},"estimatedExternalCostUsd":0.01,"estimatedModelCostUsd":0.002},"budget":{"remainingUsd":0.08,"reservedUsd":0.02,"maxToolCallsRemaining":4},"task":{"goalHash":"settlement-verification"},"history":[]}}}},"responses":{"200":{"description":"Decision only, not a destination result or settlement receipt.","content":{"application/json":{"schema":{"type":"object","required":["decision","enforcement","reasonCodes","requestFingerprint","issues","estimated"],"additionalProperties":false,"description":"Deterministic pre-execution decision. The destination tool is never executed by this service.","properties":{"decision":{"type":"string","enum":["allow","block","reuse","defer","advise"]},"enforcement":{"type":"string","enum":["execute","safe_to_skip","advisory"]},"reasonCodes":{"type":"array","items":{"type":"string"}},"requestFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"matchedCallId":{"type":"string"},"issues":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"estimated":{"type":"object","required":["preflightCostUsd","priceChargedUsd","avoidableExternalCostUsd","avoidableModelCostUsd","netSavingsUsd","billable","confidence"],"additionalProperties":false,"properties":{"preflightCostUsd":{"type":"number"},"priceChargedUsd":{"type":"number","description":"Legacy modeled actionable fee, NOT an actual settlement receipt. Paid allow/advise responses can show zero here."},"avoidableExternalCostUsd":{"type":"number"},"avoidableModelCostUsd":{"type":"number"},"netSavingsUsd":{"type":"number"},"billable":{"type":"boolean"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Rule constant, not a calibrated probability."}}},"recommendation":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string"},"resultReference":{"type":"string"}}}}},"example":{"decision":"allow","enforcement":"execute","reasonCodes":["NO_PROVEN_WASTE"],"requestFingerprint":"f2aa17128536fec8262229a5654e49e9abc18f7f7387cb571a0d035906da9e0f","issues":[],"estimated":{"preflightCostUsd":0,"priceChargedUsd":0,"avoidableExternalCostUsd":0,"avoidableModelCostUsd":0,"netSavingsUsd":0,"billable":false,"confidence":0.5}}}}},"400":{"description":"Malformed input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}},"402":{"description":"Unsettled x402 challenge; authorized clients inspect PAYMENT-REQUIRED and retry with PAYMENT-SIGNATURE. Never submit wallet secrets.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements","schema":{"type":"string"}}}},"413":{"description":"HTTP body larger than 65536 bytes.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","code","message"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"Path to the failing value"},"code":{"type":"string","description":"Stable machine-readable error code"},"message":{"type":"string"}}}}}}}}}}},"503":{"description":"X402_PAY_TO/network misconfigured, or the facilitator is unreachable."}}}},"/health":{"get":{"operationId":"health","summary":"Liveness","responses":{"200":{"description":"Worker is up","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"ok"}}}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","summary":"OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/mcp":{"get":{"operationId":"mcpGet","summary":"MCP HTTP transport","description":"Handled by the Agents SDK MCP handler.","responses":{"200":{"description":"MCP protocol response"},"405":{"description":"Method not supported by this MCP transport"}}},"post":{"operationId":"mcpPost","summary":"MCP HTTP transport","responses":{"200":{"description":"MCP protocol response"}}}}}}