{
  "openapi": "3.1.0",
  "info": {
    "title": "IntentFence Policy API",
    "version": "0.5.0",
    "description": "Guard autonomous agent actions with spend, scope, data-retention, and approval checks. The x402 endpoint returns an ES256-signed policy receipt."
  },
  "servers": [
    { "url": "https://agentpass-protocol.rmalka06.chatgpt.site" }
  ],
  "paths": {
    "/api/preflight": {
      "post": {
        "operationId": "runFreePreflight",
        "summary": "Evaluate an agent action with an unsigned preview",
        "tags": ["agent-policy", "security", "preflight"],
        "x-price": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PreflightRequest" },
              "example": {
                "subject": "did:web:crew-07",
                "action": { "type": "travel.booking", "resource": "TLV-LHR" },
                "constraints": {
                  "currency": "USD",
                  "cost_ceiling": 500,
                  "quoted_cost": 428.2,
                  "data_retention_hours": 24,
                  "human_approval": "required"
                },
                "proofs": ["human_approval"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsigned preflight decision",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PreflightDecision" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "413": { "description": "JSON body exceeds 16 KiB" },
          "415": { "description": "Unsupported content type" }
        }
      }
    },
    "/api/preflight/verified": {
      "post": {
        "operationId": "runX402Preflight",
        "summary": "Pay 0.05 USDC and receive a signed policy decision",
        "description": "x402 v2 exact payment on Base mainnet (eip155:8453). First call without payment to receive PAYMENT-REQUIRED, then retry with PAYMENT-SIGNATURE. A successful response includes an ES256 JWS receipt; settlement is returned separately in PAYMENT-RESPONSE.",
        "tags": ["agent-policy", "security", "x402", "agent-commerce"],
        "x-x402-price": "$0.05",
        "x-x402": {
          "version": 2,
          "scheme": "exact",
          "price": "0.05 USDC",
          "network": "eip155:8453",
          "asset": "USDC",
          "payTo": "0x833ca7dcdb6a681ddc0c15982ef0d609bceb3a5e"
        },
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "description": "Base64-encoded x402 v2 payment payload returned by an x402-compatible client.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PreflightRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paid preflight decision after settlement",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement result, including on-chain transaction proof.",
                "schema": { "type": "string" }
              },
              "X-IntentFence-Request-ID": {
                "description": "IntentFence audit correlation identifier.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaidPreflightDecision" }
              }
            }
          },
          "402": {
            "description": "Payment is required or the supplied payment could not be verified",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 v2 payment requirements.",
                "required": true,
                "schema": { "type": "string" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "413": { "description": "JSON body exceeds 16 KiB; a verified payment is not settled" },
          "415": { "description": "Unsupported content type; a verified payment is not settled" }
        }
      }
    },
    "/api/receipts/verify": {
      "post": {
        "operationId": "verifyIntentFenceReceipt",
        "summary": "Verify an IntentFence ES256 compact JWS receipt",
        "tags": ["agent-policy", "security", "receipt-verification"],
        "x-price": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["jws"],
                "properties": {
                  "jws": { "type": "string", "minLength": 100, "maxLength": 32768 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The receipt signature and registered claims are valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["valid", "claims"],
                  "properties": {
                    "valid": { "const": true },
                    "claims": { "$ref": "https://agentpass-protocol.rmalka06.chatgpt.site/protocol/receipt.schema.json" }
                  }
                }
              }
            }
          },
          "400": { "description": "Malformed, expired, unsupported, or invalid receipt" },
          "413": { "description": "JSON body exceeds 36 KiB" },
          "415": { "description": "Unsupported content type" }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getIntentFenceHealth",
        "summary": "Read service and protocol availability",
        "responses": {
          "200": {
            "description": "IntentFence service status",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/payments": {
      "get": {
        "operationId": "getPaymentMetadata",
        "summary": "Read live x402 price, network, recipient, and flow",
        "responses": {
          "200": {
            "description": "Public payment configuration",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "InvalidRequest": {
        "description": "Invalid JSON or preflight fields",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["error", "message"],
              "properties": {
                "error": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "PreflightRequest": {
        "type": "object",
        "required": ["subject", "action"],
        "properties": {
          "subject": { "type": "string", "minLength": 1, "maxLength": 200 },
          "action": {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": { "type": "string", "minLength": 1, "maxLength": 120 },
              "resource": { "type": "string", "maxLength": 500 }
            }
          },
          "constraints": {
            "type": "object",
            "properties": {
              "currency": { "type": "string", "maxLength": 12 },
              "cost_ceiling": { "type": "number", "minimum": 0 },
              "quoted_cost": { "type": "number", "minimum": 0 },
              "data_retention_hours": { "type": "number", "minimum": 0 },
              "human_approval": {
                "type": "string",
                "enum": ["required", "optional", "not_required"]
              }
            }
          },
          "proofs": {
            "type": "array",
            "maxItems": 20,
            "items": { "type": "string", "maxLength": 200 }
          }
        }
      },
      "PreflightDecision": {
        "type": "object",
        "required": ["intentfence", "request_id", "status", "checks", "receipt"],
        "properties": {
          "intentfence": { "type": "string", "const": "0.5" },
          "request_id": { "type": "string", "format": "uuid" },
          "status": {
            "type": "string",
            "enum": ["safe_to_proceed", "needs_review", "denied"]
          },
          "checks": { "type": "array", "items": { "type": "object" } },
          "receipt": { "type": "object" }
        }
      },
      "PaidPreflightDecision": {
        "allOf": [
          { "$ref": "#/components/schemas/PreflightDecision" },
          {
            "type": "object",
            "required": ["verification_tier"],
            "properties": {
              "verification_tier": { "type": "string", "const": "x402-settled" }
            }
          }
        ]
      }
    }
  }
}