{
  "openapi": "3.0.3",
  "info": {
    "title": "Codex Web-to-JSON API",
    "version": "1.3",
    "description": "Implemented endpoints for public product discovery, human-authorized hosted checkout, buyer-key onboarding, extraction, balance, result retrieval, and prepaid monitoring. Machine purchase and automatic replenishment are not supported."
  },
  "servers": [
    {
      "url": "https://codex-immortal-2c799423.base44.app/functions",
      "description": "Published function origin"
    }
  ],
  "paths": {
    "/web_to_json_product": {
      "get": {
        "summary": "Read public product details",
        "responses": {
          "200": { "description": "Server-owned offer, limits, authority boundary, and endpoint matrix" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_checkout": {
      "post": {
        "summary": "Create a human-authorized Stripe-hosted checkout",
        "description": "No external authentication is required. External callers send Content-Type: application/json and the buyer email only. x-base44-app-url is platform-managed for server-side return URLs; callers do not supply or control it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CheckoutRequest" },
              "example": { "email": "buyer@example.com" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hosted checkout session created. Human payment is required at the returned URL.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckoutResponse" },
                "example": { "url": "https://checkout.stripe.com/c/pay/cs_example", "orderId": "order_example", "reference": "reference_example", "units": 50 }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_access": {
      "post": {
        "summary": "Issue or rotate a buyer API key from a private delivery token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AccessRequest" },
              "example": { "token": "private_delivery_token", "rotate": false }
            }
          }
        },
        "responses": {
          "201": { "description": "One-time key issuance; response is no-store" },
          "200": { "description": "Existing-key status; response is no-store" },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_extract": {
      "post": {
        "summary": "Extract one supported public pricing page",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ExtractRequest" },
              "example": { "url": "https://vendor.example/pricing", "idempotency_key": "buyer-run-001" }
            }
          }
        },
        "responses": {
          "200": { "description": "Completed, unsupported, or released extraction result" },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_balance": {
      "get": {
        "summary": "Read the current buyer balance and recent jobs",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Buyer-scoped balance and recent jobs" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_job": {
      "get": {
        "summary": "Read one buyer-owned extraction job",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Buyer-owned job result" },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/web_to_json_watch": {
      "post": {
        "summary": "Manage buyer-scoped prepaid pricing watches",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WatchRequest" },
              "example": { "action": "create", "label": "Shortlist", "cadence": "weekly", "urls": ["https://vendor.example/pricing"] }
            }
          }
        },
        "responses": {
          "200": { "description": "Watch operation result" },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "w2j_*" }
    },
    "schemas": {
      "CheckoutRequest": {
        "type": "object",
        "required": ["email"],
        "properties": { "email": { "type": "string", "format": "email" } },
        "additionalProperties": true,
        "description": "Do not provide amount, price, currency, or units; the endpoint rejects those fields."
      },
      "CheckoutResponse": {
        "type": "object",
        "required": ["url", "orderId", "reference", "units"],
        "properties": {
          "url": { "type": "string", "format": "uri", "description": "Stripe-hosted checkout URL" },
          "orderId": { "type": "string", "description": "Not a credential or payment proof" },
          "reference": { "type": "string", "description": "Not a credential or payment proof" },
          "units": { "type": "integer", "example": 50 }
        }
      },
      "AccessRequest": {
        "type": "object",
        "required": ["token"],
        "properties": { "token": { "type": "string", "writeOnly": true }, "rotate": { "type": "boolean", "default": false } }
      },
      "ExtractRequest": {
        "type": "object",
        "required": ["url"],
        "properties": { "url": { "type": "string", "format": "uri" }, "idempotency_key": { "type": "string", "maxLength": 64 } }
      },
      "WatchRequest": {
        "type": "object",
        "properties": {
          "action": { "type": "string", "enum": ["create", "list", "get", "pause", "resume", "delete"], "default": "list" },
          "watch_id": { "type": "string" },
          "label": { "type": "string", "maxLength": 80 },
          "cadence": { "type": "string", "enum": ["daily", "weekly"], "default": "weekly" },
          "urls": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" } }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "charged_units": { "type": "integer" }, "balance": { "type": "integer" } }
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}