{
  "openapi": "3.1.0",
  "info": {
    "title": "OPX — infrastructure for machine-to-machine commerce",
    "version": "0.4.0",
    "description": "OPX builds machine-facing infrastructure and paid tools for x402 commerce. Its current live tool helps agents choose between tested x402 web-search providers before spending using recent paid performance evidence.",
    "contact": {
      "email": "oliver@opxdigital.com.au"
    },
    "x-guidance": "Call GET /api/route before spending on an x402 search provider. Paid responses include decision_id and a feedback token. After the downstream call, POST only operational outcome data to /api/outcome; never send search result content unless explicitly required."
  },
  "externalDocs": {
    "description": "OPX machine-readable usage documentation",
    "url": "https://opx-status.dev/llms.txt"
  },
  "servers": [
    {
      "url": "https://opx-status.dev"
    }
  ],
  "paths": {
    "/api/extract": {
      "post": {
        "operationId": "extractWebsiteToJSON",
        "summary": "Turn a public webpage into validated structured JSON",
        "description": "Agent submits a public HTTP(S) URL and requested fields. OPX safely retrieves the page, extracts supported structured values and returns machine-ready JSON. Payment settles only when all required fields are delivered. Public pages only; no login, CAPTCHA or paywall bypass. Field required defaults to false when omitted. Optional fields may return null and appear in missingFields; missing required fields return 422 without settlement. Validation and retrieval follow payment authorization verification; verification alone does not settle funds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "url",
                  "fields"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "minLength": 1,
                    "maxLength": 4096,
                    "description": "Public HTTP(S) webpage; private/internal addresses are rejected."
                  },
                  "fields": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "name",
                        "type"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100,
                          "description": "Unique, nonempty field name; __proto__, constructor and prototype are reserved."
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "string",
                            "number",
                            "boolean"
                          ]
                        },
                        "required": {
                          "type": "boolean",
                          "default": false,
                          "description": "If true, a missing value fails the extraction without settlement."
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "requiredPrice": {
                  "value": {
                    "url": "https://example.com/product",
                    "fields": [
                      {
                        "name": "price",
                        "type": "number",
                        "required": true
                      }
                    ]
                  }
                },
                "optionalName": {
                  "value": {
                    "url": "https://example.com/product",
                    "fields": [
                      {
                        "name": "price",
                        "type": "number",
                        "required": true
                      },
                      {
                        "name": "name",
                        "type": "string",
                        "required": false
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.005"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "USDC",
          "price_usd": 0.005,
          "amount": "5000"
        },
        "responses": {
          "200": {
            "description": "Validated extraction delivered after successful settlement of $0.005 USDC. Optional fields may be null; every required field has a valid value.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 v2 settlement receipt, including the transaction when available.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "requestId",
                    "sourceUrl",
                    "finalUrl",
                    "data",
                    "missingFields"
                  ],
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sourceUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "finalUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "data": {
                      "type": "object",
                      "description": "Requested field names mapped to typed values, or null for missing optional fields.",
                      "additionalProperties": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Requested fields whose values are null."
                    }
                  }
                },
                "examples": {
                  "requiredPrice": {
                    "value": {
                      "requestId": "3c51d4e4-88b4-4b3e-9a95-1d213aa37f85",
                      "sourceUrl": "https://example.com/product",
                      "finalUrl": "https://example.com/product",
                      "data": {
                        "price": 129.95
                      },
                      "missingFields": []
                    }
                  },
                  "optionalNameMissing": {
                    "value": {
                      "requestId": "3c51d4e4-88b4-4b3e-9a95-1d213aa37f85",
                      "sourceUrl": "https://example.com/product",
                      "finalUrl": "https://example.com/product",
                      "data": {
                        "price": 129.95,
                        "name": null
                      },
                      "missingFields": [
                        "name"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON/input or an unsafe URL, including a blocked redirect target. No settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "unsafe_url",
                  "message": "Only public HTTP(S) pages are allowed."
                }
              }
            }
          },
          "402": {
            "description": "x402 payment authorization required or rejected. Read PAYMENT-REQUIRED and authorize $0.005 USDC on Base (eip155:8453). This status may also indicate settlement failure; reconcile an uncertain transaction before creating a new authorization.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 v2 challenge on authorization-required responses. The exact scheme requests 5000 Base USDC atomic units.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "409": {
            "description": "This payment authorization is already used or in progress. No additional settlement; do not automatically replay it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "payment_already_used_or_in_progress"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 32 KB. No settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "request_too_large",
                  "message": "Request exceeds 32 KB."
                }
              }
            }
          },
          "422": {
            "description": "One or more required fields are missing. Extraction fails without settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "required_fields_missing",
                  "missingFields": [
                    "price"
                  ],
                  "missingRequired": [
                    "price"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Extraction threw or output validation failed. No settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "extraction_failed",
                  "message": "Could not extract page data."
                }
              }
            }
          },
          "502": {
            "description": "Page retrieval failed (including HTTP 403/404/5xx), exceeded 1 MiB or the redirect limit, or used unsupported content. Failed retrieval never settles. A facilitator failure may also return 502; reconcile any uncertain settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "upstream_http_error",
                  "message": "Page returned HTTP 403."
                }
              }
            }
          },
          "503": {
            "description": "Extraction is disabled, payment initialization is unavailable, or durable replay storage cannot authorize proceeding. No extraction settlement is started on these failures.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "payment_replay_guard_unavailable"
                }
              }
            }
          },
          "504": {
            "description": "The 10-second page retrieval deadline expired. No settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "missingFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "missingRequired": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "error": "retrieval_timeout",
                  "message": "Page retrieval timed out."
                }
              }
            }
          }
        }
      }
    },
    "/api/route": {
      "get": {
        "operationId": "routeX402WebSearch",
        "summary": "Choose the best currently tested x402 web-search provider for a task",
        "description": "Returns a primary provider and independent fallbacks ranked from paid probe evidence including functional success, latency, price, freshness, result diversity and task fit.",
        "parameters": [
          {
            "name": "task",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "web-search"
              ],
              "default": "web-search"
            }
          },
          {
            "name": "intent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "web",
                "news",
                "research",
                "known-page",
                "company"
              ],
              "default": "web"
            }
          },
          {
            "name": "freshness",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "day",
                "week",
                "month"
              ],
              "default": "any"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Optional routing context. OPX stores only a hash of q in decision telemetry.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "max_latency_ms",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.002"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Routing decision with decision_id and authenticated feedback credential.",
            "content": {
              "application/json": {
                "example": {
                  "task": "web-search",
                  "decision_id": "3c51d4e4-88b4-4b3e-9a95-1d213aa37f85",
                  "feedback": {
                    "outcome_url": "https://opx-status.dev/api/outcome",
                    "token": "opaque-paid-client-token",
                    "max_attempts": 5
                  },
                  "request": {
                    "intent": "news",
                    "freshness": "week",
                    "budget_usd": 0.02
                  },
                  "primary": {
                    "endpoint_id": 1,
                    "provider": "Exa",
                    "upstream": "exa",
                    "score": 84.1,
                    "confidence": 0.55
                  },
                  "fallbacks": [
                    {
                      "endpoint_id": 8,
                      "provider": "Vaaya",
                      "upstream": "brave"
                    }
                  ],
                  "confidence": 0.5
                }
              }
            }
          },
          "402": {
            "description": "Payment Required. Pay $0.002 USDC on Base using x402 and retry."
          }
        }
      }
    },
    "/api/outcome": {
      "post": {
        "operationId": "reportOPXOutcome",
        "security": [],
        "summary": "Report an operational downstream outcome for a paid OPX decision",
        "description": "Free feedback endpoint. Requires the decision_id and opaque feedback token returned only in the paid /api/route response. Client outcomes are stored for calibration and are not yet directly used for ranking.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "decision_id",
                  "feedback_token",
                  "selected_endpoint_id",
                  "success"
                ],
                "properties": {
                  "decision_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "feedback_token": {
                    "type": "string"
                  },
                  "attempt": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 1
                  },
                  "selected_endpoint_id": {
                    "type": "integer"
                  },
                  "success": {
                    "type": "boolean"
                  },
                  "latency_ms": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "price_usd": {
                    "type": "number",
                    "minimum": 0
                  },
                  "schema_pass": {
                    "type": "boolean"
                  },
                  "error_class": {
                    "type": "string"
                  },
                  "meta": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Outcome accepted."
          },
          "401": {
            "description": "Invalid feedback token."
          },
          "409": {
            "description": "Attempt already reported."
          }
        }
      }
    }
  }
}