{
  "openapi": "3.1.0",
  "info": {
    "title": "Extracto API",
    "version": "1.0.0",
    "description": "Turn any public web page into clean markdown or structured JSON in one call.\n\nThree operations share the same renderer (JavaScript included, with an anti-bot\nstealth fallback):\n- `POST /v1/scrape`: render a page into markdown / html / text / links (and optionally structured JSON). Default is clean markdown.\n- `POST /v1/extract`: render a page and return JSON validated against a schema you describe.\n- `POST /v1/map`: discover the URLs of a site (robots.txt + sitemap + on-page links).\n\n## Authentication\nSend your API key as a bearer token. Create keys in the dashboard.\n\n```\nAuthorization: Bearer exa_live_...\n```\n\n## Quickstart: scrape a page to markdown (curl)\n```bash\ncurl -X POST https://app.getextracto.dev/v1/scrape \\\n  -H \"Authorization: Bearer exa_live_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com/blog/launch\",\"formats\":[\"markdown\",\"links\"]}'\n```\n\n## Quickstart: extract structured JSON (curl)\n```bash\ncurl -X POST https://app.getextracto.dev/v1/extract \\\n  -H \"Authorization: Bearer exa_live_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com/product/123\",\"schema\":{\"title\":\"string\",\"price\":\"number\",\"tags\":[\"string\"]}}'\n```\n\n## Quickstart (JS/TS)\n```ts\nconst res = await fetch(\"https://app.getextracto.dev/v1/extract\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.EXTRACTO_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/product/123\",\n    \"schema\": {\n      \"title\": \"string\",\n      \"price\": \"number\",\n      \"tags\": [\n        \"string\"\n      ]\n    }\n  }),\n});\nconst data = await res.json();\n```\n\n## Quickstart (Python)\n```python\nimport os\nimport requests\n\nres = requests.post(\n    \"https://app.getextracto.dev/v1/extract\",\n    headers={\"Authorization\": f\"Bearer {os.environ['EXTRACTO_API_KEY']}\"},\n    json={\n        \"url\": \"https://example.com/product/123\",\n        \"schema\": {\n            \"title\": \"string\",\n            \"price\": \"number\",\n            \"tags\": [\n                \"string\"\n            ]\n        }\n    },\n)\ndata = res.json()\n```\n\n## Schema language\nThe `schema` field is a shorthand: each value is a type literal\n(`string`, `number`, `boolean`, `array`, `object`), an array `[descriptor]`\nfor a list, or a nested object `{ ... }`. The response `data` mirrors your schema;\na field that cannot be found is `null`. Limits: at most 15 top-level\nfields and 2048 bytes.\n\n## Quota and credits\nEach successful call consumes credits from your monthly quota. The cost depends only\non the operation, not on the engine: a request served by the anti-bot `stealth`\nengine (residential proxy + JS rendering) costs exactly the same as one served by the\nstandard Cloudflare renderer (`cf`). The price is flat so it is never a surprise; the\n`engine` field still reports which renderer ran.\n\n| Operation | Credits |\n| --- | --- |\n| `scrape` (markdown/html/text/links, no LLM) | 1 |\n| `extract` (render + structured JSON via LLM) | 5 |\n| `map` (discover a site's URLs) | 1 |\n| cache hit (any operation) | 0 |\n| any failure (non-2xx) | 0 |\n\nPrice is flat per operation: the anti-bot `stealth` engine costs the same as the standard `cf` engine, so a request never costs more than you expect.\n\nTwo cases never cost anything: a **cache hit** (you already paid for the first\nfetch) and **any failure** (a non-2xx response). Every response reports its exact\ncharge in `credits_used` and the engine used in `engine`, and sets the\n`X-Credits-Used` / `X-Credits-Remaining` headers. See the response codes below for\nthe full error contract.\n\n## Reliability: examples and retries\nPass an optional `examples` array (up to 3) of correctly shaped outputs\nto anchor the format the model returns (decimal style, units, date format). Each\n`example.output` must match your `schema`. The extractor also retries automatically on\na transient model fault, so a single blip does not surface as a failure.\n\n## Async jobs (no time ceiling)\nFor heavy or anti-bot pages, submit a job instead of waiting on the synchronous call.\n`POST /v1/jobs` returns a job id immediately; poll `GET /v1/jobs/{id}` or receive a\nsigned webhook when it finishes. Set a per-job `webhook_url`, or configure reusable\nendpoints in the dashboard.\n\n### Webhook signature\nEach delivery carries an `X-Extracto-Signature: t=<unix>,v1=<hex>` header. Verify\nit by recomputing HMAC-SHA256 over `${t}.${rawBody}` with your endpoint secret and\ncomparing in constant time (the same scheme Stripe uses).\n\n## MCP server (for AI agents)\nExtracto ships a hosted Model Context Protocol server so an AI assistant can scrape,\nextract, map and check jobs as native tools. The endpoint is:\n\n```\nhttps://mcp.getextracto.dev\n```\n\nAuthenticate with the same `exa_live_...` API key as a bearer token (no OAuth). The\nserver exposes four tools: `scrape_page` (read ONE page as markdown/text/html),\n`extract_data` (get specific structured fields back as JSON), `map_site` (discover\nthe URLs of a site) and `get_job` (check an async job).\n\nAdd it in Claude Code:\n```bash\nclaude mcp add --transport http extracto https://mcp.getextracto.dev \\\n  --header \"Authorization: Bearer exa_live_...\"\n```\n\nAdd it in Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json` in your project):\n```json\n{\n  \"mcpServers\": {\n    \"extracto\": {\n      \"url\": \"https://mcp.getextracto.dev\",\n      \"headers\": { \"Authorization\": \"Bearer exa_live_...\" }\n    }\n  }\n}\n```\n\n## Migrating from Firecrawl\nIf you already call Firecrawl, switching is mostly a base-URL change. Extracto exposes\nhappy-path-compatible routes under `/fc/v1/` that accept Firecrawl-shaped requests and\nreturn the Firecrawl envelope `{ \"success\": true, \"data\": { ... } }`:\n- `POST /fc/v1/scrape` maps to `/v1/scrape`. It honors `formats` and `jsonOptions.schema` (these change the output); other Firecrawl tuning fields (`onlyMainContent`, `includeTags`/`excludeTags`, `waitFor`, etc.) are accepted but ignored, so an existing payload keeps working without erroring.\n- `POST /fc/v1/map` maps to `/v1/map` (honors `url`, `limit`, `search`, `includeSubdomains`).\n\nPoint your Firecrawl client's base URL at `https://app.getextracto.dev/fc` and use your Extracto\n`exa_live_...` key as the bearer token. For new code prefer the native `/v1/` routes\n(the `{ error: { code, message } }` envelope and the credit table above apply there);\nthe `/fc/` surface is a compatibility shim covering the common scrape/map subset, not\nevery Firecrawl field."
  },
  "servers": [
    {
      "url": "https://app.getextracto.dev",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/extract": {
      "post": {
        "operationId": "extract",
        "summary": "Extract structured data from a web page",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Optional. A unique key per logical request; a retry with the same key replays the original response instead of re-running (and re-charging) the work."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExtractRequest"
              },
              "example": {
                "url": "https://example.com/product/123",
                "schema": {
                  "title": "string",
                  "price": "number",
                  "in_stock": "boolean",
                  "tags": [
                    "string"
                  ],
                  "brand": {
                    "name": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted data matching the requested schema.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractResponse"
                },
                "example": {
                  "data": {
                    "title": "Acme Widget",
                    "price": 19.99,
                    "in_stock": true,
                    "tags": [
                      "durable",
                      "blue"
                    ],
                    "brand": {
                      "name": "Acme"
                    }
                  },
                  "extracted_in_ms": 5421,
                  "cached": false,
                  "credits_used": 5
                }
              }
            }
          },
          "400": {
            "description": "bad_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "bad_request": {
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Request body must be valid JSON."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Provide a valid API key as `Authorization: Bearer exa_live_...`."
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "quota_exceeded": {
                    "value": {
                      "error": {
                        "code": "quota_exceeded",
                        "message": "Monthly page quota exhausted for the current period."
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "idempotency_in_flight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_in_flight": {
                    "value": {
                      "error": {
                        "code": "idempotency_in_flight",
                        "message": "A request with this Idempotency-Key is still in progress. Retry shortly."
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "idempotency_conflict, url_invalid, blocked_domain, schema_invalid, schema_too_large, schema_too_many_fields, schema_injection, schema_mismatch, browser_error, browser_blocked, upstream_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "This Idempotency-Key was already used for a request with a different body."
                      }
                    }
                  },
                  "url_invalid": {
                    "value": {
                      "error": {
                        "code": "url_invalid",
                        "message": "The url must be a valid public HTTPS URL."
                      }
                    }
                  },
                  "blocked_domain": {
                    "value": {
                      "error": {
                        "code": "blocked_domain",
                        "message": "This domain is not supported (authentication-walled or restricted)."
                      }
                    }
                  },
                  "schema_invalid": {
                    "value": {
                      "error": {
                        "code": "schema_invalid",
                        "message": "The schema is malformed or uses an unsupported type."
                      }
                    }
                  },
                  "schema_too_large": {
                    "value": {
                      "error": {
                        "code": "schema_too_large",
                        "message": "The schema exceeds the maximum size."
                      }
                    }
                  },
                  "schema_too_many_fields": {
                    "value": {
                      "error": {
                        "code": "schema_too_many_fields",
                        "message": "The schema has too many top-level fields."
                      }
                    }
                  },
                  "schema_injection": {
                    "value": {
                      "error": {
                        "code": "schema_injection",
                        "message": "The schema contains a disallowed value."
                      }
                    }
                  },
                  "schema_mismatch": {
                    "value": {
                      "error": {
                        "code": "schema_mismatch",
                        "message": "Extracted data did not match the requested schema."
                      }
                    }
                  },
                  "browser_error": {
                    "value": {
                      "error": {
                        "code": "browser_error",
                        "message": "The page could not be rendered."
                      }
                    }
                  },
                  "browser_blocked": {
                    "value": {
                      "error": {
                        "code": "browser_blocked",
                        "message": "The page is protected by anti-bot and could not be retrieved."
                      }
                    }
                  },
                  "upstream_error": {
                    "value": {
                      "error": {
                        "code": "upstream_error",
                        "message": "The target page returned an error status and could not be rendered."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, ip_rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "Too many requests. Slow down and retry shortly."
                      }
                    }
                  },
                  "ip_rate_limited": {
                    "value": {
                      "error": {
                        "code": "ip_rate_limited",
                        "message": "Daily limit reached for this network on the free plan. Upgrade for higher limits."
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "internal_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "internal_error": {
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "An unexpected error occurred."
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "timeout, browser_unavailable, model_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "timeout": {
                    "value": {
                      "error": {
                        "code": "timeout",
                        "message": "The extraction timed out."
                      }
                    }
                  },
                  "browser_unavailable": {
                    "value": {
                      "error": {
                        "code": "browser_unavailable",
                        "message": "The rendering service is temporarily at capacity. Retry after a short delay."
                      }
                    }
                  },
                  "model_error": {
                    "value": {
                      "error": {
                        "code": "model_error",
                        "message": "The extraction model failed."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/scrape": {
      "post": {
        "operationId": "scrape",
        "summary": "Render a page into markdown, html, text, links or JSON",
        "description": "Renders the page once (JavaScript included) and projects it into the requested formats. Default is clean markdown. Include 'json' (with a schema) to also run the structured extractor. One render, one bill: see the credit table.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Optional. A unique key per logical request; a retry with the same key replays the original response instead of re-running (and re-charging) the work."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScrapeRequest"
              },
              "example": {
                "url": "https://example.com/blog/launch",
                "formats": [
                  "markdown",
                  "links"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The page rendered into the requested formats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScrapeResponse"
                },
                "example": {
                  "data": {
                    "markdown": "# Launch\n\nWe shipped today. Read the [notes](https://example.com/notes).",
                    "links": [
                      "https://example.com/notes",
                      "https://example.com/pricing"
                    ]
                  },
                  "extracted_in_ms": 1840,
                  "cached": false,
                  "credits_used": 1,
                  "engine": "cf"
                }
              }
            }
          },
          "400": {
            "description": "bad_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "bad_request": {
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Request body must be valid JSON."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Provide a valid API key as `Authorization: Bearer exa_live_...`."
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "quota_exceeded": {
                    "value": {
                      "error": {
                        "code": "quota_exceeded",
                        "message": "Monthly page quota exhausted for the current period."
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "idempotency_in_flight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_in_flight": {
                    "value": {
                      "error": {
                        "code": "idempotency_in_flight",
                        "message": "A request with this Idempotency-Key is still in progress. Retry shortly."
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "idempotency_conflict, url_invalid, blocked_domain, schema_invalid, schema_too_large, schema_too_many_fields, schema_injection, schema_mismatch, browser_error, browser_blocked, upstream_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "This Idempotency-Key was already used for a request with a different body."
                      }
                    }
                  },
                  "url_invalid": {
                    "value": {
                      "error": {
                        "code": "url_invalid",
                        "message": "The url must be a valid public HTTPS URL."
                      }
                    }
                  },
                  "blocked_domain": {
                    "value": {
                      "error": {
                        "code": "blocked_domain",
                        "message": "This domain is not supported (authentication-walled or restricted)."
                      }
                    }
                  },
                  "schema_invalid": {
                    "value": {
                      "error": {
                        "code": "schema_invalid",
                        "message": "The schema is malformed or uses an unsupported type."
                      }
                    }
                  },
                  "schema_too_large": {
                    "value": {
                      "error": {
                        "code": "schema_too_large",
                        "message": "The schema exceeds the maximum size."
                      }
                    }
                  },
                  "schema_too_many_fields": {
                    "value": {
                      "error": {
                        "code": "schema_too_many_fields",
                        "message": "The schema has too many top-level fields."
                      }
                    }
                  },
                  "schema_injection": {
                    "value": {
                      "error": {
                        "code": "schema_injection",
                        "message": "The schema contains a disallowed value."
                      }
                    }
                  },
                  "schema_mismatch": {
                    "value": {
                      "error": {
                        "code": "schema_mismatch",
                        "message": "Extracted data did not match the requested schema."
                      }
                    }
                  },
                  "browser_error": {
                    "value": {
                      "error": {
                        "code": "browser_error",
                        "message": "The page could not be rendered."
                      }
                    }
                  },
                  "browser_blocked": {
                    "value": {
                      "error": {
                        "code": "browser_blocked",
                        "message": "The page is protected by anti-bot and could not be retrieved."
                      }
                    }
                  },
                  "upstream_error": {
                    "value": {
                      "error": {
                        "code": "upstream_error",
                        "message": "The target page returned an error status and could not be rendered."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, ip_rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "Too many requests. Slow down and retry shortly."
                      }
                    }
                  },
                  "ip_rate_limited": {
                    "value": {
                      "error": {
                        "code": "ip_rate_limited",
                        "message": "Daily limit reached for this network on the free plan. Upgrade for higher limits."
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "internal_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "internal_error": {
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "An unexpected error occurred."
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "timeout, browser_unavailable, model_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "timeout": {
                    "value": {
                      "error": {
                        "code": "timeout",
                        "message": "The extraction timed out."
                      }
                    }
                  },
                  "browser_unavailable": {
                    "value": {
                      "error": {
                        "code": "browser_unavailable",
                        "message": "The rendering service is temporarily at capacity. Retry after a short delay."
                      }
                    }
                  },
                  "model_error": {
                    "value": {
                      "error": {
                        "code": "model_error",
                        "message": "The extraction model failed."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/map": {
      "post": {
        "operationId": "map",
        "summary": "Discover a site's page URLs",
        "description": "Discovers URLs from robots.txt, sitemap.xml and on-page links, deduped and limited to the same registrable domain. No LLM; flat cost of 1 credit per call. Every discovered URL is SSRF-checked before it is returned.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MapRequest"
              },
              "example": {
                "url": "https://example.com",
                "limit": 100
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The discovered, deduped, same-domain URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MapResponse"
                },
                "example": {
                  "links": [
                    "https://example.com/",
                    "https://example.com/pricing",
                    "https://example.com/blog/launch",
                    "https://example.com/docs"
                  ],
                  "cached": false,
                  "credits_used": 1,
                  "engine": "cf"
                }
              }
            }
          },
          "400": {
            "description": "bad_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "bad_request": {
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Request body must be valid JSON."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Provide a valid API key as `Authorization: Bearer exa_live_...`."
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "quota_exceeded": {
                    "value": {
                      "error": {
                        "code": "quota_exceeded",
                        "message": "Monthly page quota exhausted for the current period."
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "idempotency_in_flight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_in_flight": {
                    "value": {
                      "error": {
                        "code": "idempotency_in_flight",
                        "message": "A request with this Idempotency-Key is still in progress. Retry shortly."
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "idempotency_conflict, url_invalid, blocked_domain, schema_invalid, schema_too_large, schema_too_many_fields, schema_injection, schema_mismatch, browser_error, browser_blocked, upstream_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency_conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "This Idempotency-Key was already used for a request with a different body."
                      }
                    }
                  },
                  "url_invalid": {
                    "value": {
                      "error": {
                        "code": "url_invalid",
                        "message": "The url must be a valid public HTTPS URL."
                      }
                    }
                  },
                  "blocked_domain": {
                    "value": {
                      "error": {
                        "code": "blocked_domain",
                        "message": "This domain is not supported (authentication-walled or restricted)."
                      }
                    }
                  },
                  "schema_invalid": {
                    "value": {
                      "error": {
                        "code": "schema_invalid",
                        "message": "The schema is malformed or uses an unsupported type."
                      }
                    }
                  },
                  "schema_too_large": {
                    "value": {
                      "error": {
                        "code": "schema_too_large",
                        "message": "The schema exceeds the maximum size."
                      }
                    }
                  },
                  "schema_too_many_fields": {
                    "value": {
                      "error": {
                        "code": "schema_too_many_fields",
                        "message": "The schema has too many top-level fields."
                      }
                    }
                  },
                  "schema_injection": {
                    "value": {
                      "error": {
                        "code": "schema_injection",
                        "message": "The schema contains a disallowed value."
                      }
                    }
                  },
                  "schema_mismatch": {
                    "value": {
                      "error": {
                        "code": "schema_mismatch",
                        "message": "Extracted data did not match the requested schema."
                      }
                    }
                  },
                  "browser_error": {
                    "value": {
                      "error": {
                        "code": "browser_error",
                        "message": "The page could not be rendered."
                      }
                    }
                  },
                  "browser_blocked": {
                    "value": {
                      "error": {
                        "code": "browser_blocked",
                        "message": "The page is protected by anti-bot and could not be retrieved."
                      }
                    }
                  },
                  "upstream_error": {
                    "value": {
                      "error": {
                        "code": "upstream_error",
                        "message": "The target page returned an error status and could not be rendered."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, ip_rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "Too many requests. Slow down and retry shortly."
                      }
                    }
                  },
                  "ip_rate_limited": {
                    "value": {
                      "error": {
                        "code": "ip_rate_limited",
                        "message": "Daily limit reached for this network on the free plan. Upgrade for higher limits."
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "internal_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "internal_error": {
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "An unexpected error occurred."
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "timeout, browser_unavailable, model_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "timeout": {
                    "value": {
                      "error": {
                        "code": "timeout",
                        "message": "The extraction timed out."
                      }
                    }
                  },
                  "browser_unavailable": {
                    "value": {
                      "error": {
                        "code": "browser_unavailable",
                        "message": "The rendering service is temporarily at capacity. Retry after a short delay."
                      }
                    }
                  },
                  "model_error": {
                    "value": {
                      "error": {
                        "code": "model_error",
                        "message": "The extraction model failed."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "operationId": "createJob",
        "summary": "Submit an async extraction job",
        "description": "Validates and enqueues the extraction, returning a job id immediately (202). Poll GET /v1/jobs/{id} or receive a signed webhook on completion.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Optional. A unique key per logical request; a retry with the same key replays the original response instead of re-running (and re-charging) the work."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateJobRequest"
              },
              "example": {
                "url": "https://example.com/product/123",
                "schema": {
                  "title": "string",
                  "price": "number",
                  "in_stock": "boolean",
                  "tags": [
                    "string"
                  ],
                  "brand": {
                    "name": "string"
                  }
                },
                "webhook_url": "https://your-app.com/extracto/callback"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted and queued.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                },
                "description": "URL of the job resource to poll (GET /v1/jobs/{id})."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobAccepted"
                },
                "example": {
                  "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c",
                  "status": "pending",
                  "status_url": "https://app.getextracto.dev/v1/jobs/4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listJobs",
        "summary": "List your recent jobs",
        "responses": {
          "200": {
            "description": "Newest-first page of your jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    }
                  }
                },
                "example": {
                  "jobs": [
                    {
                      "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c",
                      "status": "success",
                      "url": "https://example.com/product/123",
                      "result": {
                        "title": "Acme Widget",
                        "price": 19.99,
                        "in_stock": true,
                        "tags": [
                          "durable",
                          "blue"
                        ],
                        "brand": {
                          "name": "Acme"
                        }
                      },
                      "error": null,
                      "credits_used": 5,
                      "created_at": 1700000000000,
                      "completed_at": 1700000004000
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "operationId": "getJob",
        "summary": "Get a job status/result",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The job, with its result once complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c",
                  "status": "success",
                  "url": "https://example.com/product/123",
                  "result": {
                    "title": "Acme Widget",
                    "price": 19.99,
                    "in_stock": true,
                    "tags": [
                      "durable",
                      "blue"
                    ],
                    "brand": {
                      "name": "Acme"
                    }
                  },
                  "error": null,
                  "credits_used": 5,
                  "created_at": 1700000000000,
                  "completed_at": 1700000004000
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "No job with that id."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "cancelJob",
        "summary": "Cancel a still-pending job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job canceled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c",
                  "status": "canceled"
                }
              }
            }
          },
          "409": {
            "description": "not_cancelable (already running or finished)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_cancelable",
                    "message": "Job is processing and can no longer be canceled."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key, sent as `Authorization: Bearer exa_live_...`."
      }
    },
    "schemas": {
      "ExtractRequest": {
        "type": "object",
        "required": [
          "url",
          "schema"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public HTTPS URL of the page to extract from."
          },
          "schema": {
            "type": "object",
            "description": "Shorthand schema. Each value is a type literal (string, number, boolean, array, object), an array [descriptor], or a nested object. Max 15 top-level fields, 2048 bytes.",
            "additionalProperties": true
          },
          "examples": {
            "type": "array",
            "description": "Optional few-shot examples (up to 3) to anchor output format. Each item has an optional source `url` and an `output` that must match the schema shape.",
            "items": {
              "type": "object",
              "required": [
                "output"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "output": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "ExtractResponse": {
        "type": "object",
        "required": [
          "data",
          "extracted_in_ms",
          "cached",
          "credits_used"
        ],
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Mirrors your requested schema; unfound fields are null."
          },
          "extracted_in_ms": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          },
          "credits_used": {
            "type": "integer",
            "description": "Quota credits this call consumed: a flat 5 on any engine (the anti-bot 'stealth' path is not charged extra), 0 on a cache hit."
          }
        }
      },
      "ScrapeRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public HTTPS URL of the page to render."
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "markdown",
                "html",
                "text",
                "links",
                "json"
              ]
            },
            "default": [
              "markdown"
            ],
            "description": "Output formats to project the single render into. Defaults to ['markdown']. Include 'json' to also run the structured extractor (requires `schema`)."
          },
          "schema": {
            "type": "object",
            "additionalProperties": true,
            "description": "Required only when `formats` includes 'json'. Same shorthand grammar as /v1/extract: a type literal (string, number, boolean, array, object), an array [descriptor], or a nested object. Max 15 top-level fields, 2048 bytes."
          },
          "examples": {
            "type": "array",
            "description": "Optional few-shot examples (up to 3) used by the 'json' format to anchor output formatting.",
            "items": {
              "type": "object",
              "required": [
                "output"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "output": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "ScrapeResponse": {
        "type": "object",
        "required": [
          "data",
          "extracted_in_ms",
          "cached",
          "credits_used",
          "engine"
        ],
        "properties": {
          "data": {
            "type": "object",
            "description": "The rendered page projected into the requested formats. Each field is present only when its format was requested.",
            "properties": {
              "markdown": {
                "type": "string",
                "description": "Present when 'markdown' was requested. Clean markdown of the page."
              },
              "html": {
                "type": "string",
                "description": "Present when 'html' was requested. Sanitized HTML of the page."
              },
              "text": {
                "type": "string",
                "description": "Present when 'text' was requested. Plain text of the page."
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uri"
                },
                "description": "Present when 'links' was requested. Absolute links found on the page."
              },
              "json": {
                "type": "object",
                "additionalProperties": true,
                "description": "Present when 'json' was requested. Structured data matching your schema."
              }
            }
          },
          "extracted_in_ms": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          },
          "credits_used": {
            "type": "integer",
            "description": "Quota credits this call consumed: a flat 1 on any engine (the anti-bot 'stealth' path is not charged extra), 0 on a cache hit. Including 'json' bills as an extract."
          },
          "engine": {
            "type": "string",
            "enum": [
              "cf",
              "stealth"
            ],
            "description": "Which renderer served the page: 'cf' (standard) or 'stealth' (anti-bot)."
          }
        }
      },
      "MapRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public HTTPS URL of the site whose page URLs to discover."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5000,
            "default": 100,
            "description": "Max URLs to return (flat cost, no per-URL billing). Default 100, max 5000."
          },
          "includeSubdomains": {
            "type": "boolean",
            "default": false,
            "description": "Include URLs on subdomains of the registrable domain."
          },
          "search": {
            "type": "string",
            "description": "Optional substring to keep only matching URLs."
          }
        }
      },
      "MapResponse": {
        "type": "object",
        "required": [
          "links",
          "cached",
          "credits_used",
          "engine"
        ],
        "properties": {
          "links": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Discovered, deduped, same-domain, SSRF-checked URLs."
          },
          "cached": {
            "type": "boolean"
          },
          "credits_used": {
            "type": "integer",
            "description": "Flat 1 credit per call (no LLM), 0 on a cache hit."
          },
          "engine": {
            "type": "string",
            "enum": [
              "cf",
              "stealth"
            ],
            "description": "Always 'cf' for map (flat cost, no per-engine render split)."
          }
        }
      },
      "CreateJobRequest": {
        "type": "object",
        "required": [
          "url",
          "schema"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "output"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "output": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional per-job result callback. When omitted, your active dashboard webhooks receive the result."
          }
        }
      },
      "JobAccepted": {
        "type": "object",
        "required": [
          "id",
          "status",
          "status_url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Job": {
        "type": "object",
        "required": [
          "id",
          "status",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "success",
              "failed"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "result": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Extracted data once the job succeeds, else null."
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "credits_used": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at": {
            "type": "integer"
          },
          "completed_at": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "description": "Body POSTed to a result webhook. Signed with an `X-Extracto-Signature: t=<unix>,v1=<hex>` header (HMAC-SHA256 over `${t}.${rawBody}`).",
        "required": [
          "type",
          "job"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "job.completed"
            ]
          },
          "job": {
            "$ref": "#/components/schemas/Job"
          }
        },
        "example": {
          "type": "job.completed",
          "job": {
            "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c",
            "status": "success",
            "url": "https://example.com/product/123",
            "result": {
              "title": "Acme Widget",
              "price": 19.99,
              "in_stock": true,
              "tags": [
                "durable",
                "blue"
              ],
              "brand": {
                "name": "Acme"
              }
            },
            "error": null,
            "credits_used": 5,
            "completed_at": 1700000004000
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
