{
  "openapi": "3.1.0",
  "info": {
    "title": "DoubleCrawl API",
    "version": "1.0.0",
    "summary": "Ask for a page, get the page.",
    "description": "Live page fetch API by DoubleData. DoubleCrawl fetches a URL (a web page, a JSON or mobile app API) through the route that works for that site, retries for up to 30 seconds and returns the site's own answer. Only delivered pages are billed. AI agents can use the MCP server at https://mcp.doublecrawl.com/mcp instead of this HTTP API.",
    "contact": {
      "name": "DoubleData",
      "email": "sales@doubledata.com",
      "url": "https://doublecrawl.com/"
    },
    "x-llms-txt": "https://doublecrawl.com/llms.txt"
  },
  "externalDocs": {
    "description": "Documentation",
    "url": "https://doublecrawl.com/docs/"
  },
  "servers": [
    {
      "url": "https://api.doublecrawl.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/request": {
      "post": {
        "operationId": "fetchPage",
        "summary": "Fetch a page",
        "description": "Returns the target site's status, headers and body as the site sent them. Branch on the X-DD-Target-Outcome header, not on the HTTP status. Set your client timeout to 40 seconds or more: the service keeps trying for up to 30 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FetchRequest"
              },
              "examples": {
                "example": {
                  "value": {
                    "url": "https://shop.example/running-shoes",
                    "country": "de"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "The target site's own answer (any status). Billed only when X-DD-Target-Outcome is delivered.",
            "headers": {
              "X-DD-Target-Outcome": {
                "$ref": "#/components/headers/TargetOutcome"
              },
              "X-DD-Credits": {
                "description": "Credits charged for this request: 1 at Level 1, 4 at Level 2, 25 at Level 3, 0 when not delivered.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-DD-Request-Id": {
                "description": "Quote it in support requests.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "description": "Out of credits. Top up or upgrade at https://app.doublecrawl.com/.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Concurrency limit of your plan reached. Retry when one of your requests finishes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "target_unreached: the site could not be reached within 30 seconds. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from https://app.doublecrawl.com/ (5,000 free credits on sign-up)."
      }
    },
    "headers": {
      "TargetOutcome": {
        "description": "delivered: you got the page. absent: the site says it does not exist (e.g. 404; not billed). refused: the site still refused after all attempts (not billed).",
        "schema": {
          "type": "string",
          "enum": [
            "delivered",
            "absent",
            "refused"
          ]
        }
      }
    },
    "responses": {
      "Error": {
        "description": "The request was not accepted.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "FetchRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute http(s) URL to fetch: a web page, a JSON or mobile app API, or any other endpoint."
          },
          "country": {
            "type": "string",
            "pattern": "^[a-z]{2}$",
            "description": "ISO 3166-1 alpha-2 code, lowercase. Leave it out unless you need one country's results: by default the location with the best success rate for the site is used."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST",
              "HEAD"
            ],
            "default": "GET"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Extra request headers. Browser identity headers are set for you."
          },
          "body": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Request body for POST."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "examples": [
                  "invalid_request",
                  "unauthorized",
                  "out_of_credits",
                  "concurrency_limit",
                  "target_unreached"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
