{
  "openapi": "3.1.0",
  "info": {
    "title": "Backfill Fetch API",
    "version": "1.0.0",
    "description": "Pay-per-fetch web extraction for agents: POST a URL, get the page back as clean markdown. Plain fetches are free within a daily allowance; cache hits cost $0.005 and fresh rendered fetches $0.05 via x402 v2 (USDC on Base). Payment settles only after content is delivered — a failed fetch is never charged. A second endpoint, /v1/extract (Backfill Extract), returns the page's data as JSON matching a caller-supplied schema: $0.15 fresh, $0.05 for a cached result, on the same terms."
  },
  "servers": [
    {
      "url": "https://backfill.top"
    }
  ],
  "paths": {
    "/v1/fetch": {
      "post": {
        "summary": "Fetch a web page and return it as markdown",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The http(s) URL to fetch"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "plain",
                      "render"
                    ],
                    "default": "auto"
                  },
                  "include_html": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{url, status, markdown, cached, fetched_at, charged} — status is \"ok\", or \"blocked\"/\"error\" for an uncharged plain-mode failure"
          },
          "400": {
            "description": "Invalid request (bad URL, credentials in URL, private/loopback target, unknown mode)"
          },
          "402": {
            "description": "Payment required (x402 v2 terms in body and PAYMENT-REQUIRED header)"
          },
          "502": {
            "description": "The fetch failed after payment verification; the payment was NOT settled"
          }
        }
      }
    },
    "/v1/extract": {
      "post": {
        "summary": "Extract structured data from a web page as JSON matching a JSON Schema",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The http(s) URL to extract from"
                  },
                  "schema": {
                    "type": "object",
                    "description": "A JSON Schema object describing the data to extract (max 8 KB serialized, max nesting depth 6)"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "plain",
                      "render"
                    ],
                    "default": "auto"
                  }
                },
                "required": [
                  "url",
                  "schema"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{url, status, data, cached, fetched_at, charged} — data is the extracted JSON matching the supplied schema"
          },
          "400": {
            "description": "Invalid request (bad URL, credentials in URL, private/loopback target, unknown mode, missing/invalid/oversized schema)"
          },
          "402": {
            "description": "Payment required (x402 v2 terms in body and PAYMENT-REQUIRED header): $0.15 fresh, $0.05 for a cached result"
          },
          "502": {
            "description": "The fetch or the extraction failed after payment verification; the payment was NOT settled"
          },
          "503": {
            "description": "Extraction is not available on this deployment; nothing is charged"
          }
        }
      }
    }
  }
}