{"openapi":"3.1.0","info":{"title":"Scrapestack API","version":"1.0.0","description":"The scrapestack API was built to offer a simple REST API interface for scraping web pages at scale without having to programatically deal with geolocations, IP blocks or CAPTCHAs. The API supports a series of features essential to web scraping, such as JavaScript rendering, custom HTTP headers, various geo-targets, POST/PUT requests and an option to use premium residential proxies instead of datacenter proxies."},"servers":[{"url":"https://api.scrapestack.com"}],"security":[],"tags":[],"externalDocs":{"description":"Official Scrapestack documentation (reference)","url":"https://scrapestack.com/documentation"},"paths":{"/scrape":{"get":{"summary":"Basic Scrape","operationId":"scrapeGet","description":"To scrape a web page using the scrapestack API, simply use the API's base endpoint and append the `URL` you would like to scrape as well as your API access key as GET parameters.\n","parameters":[{"$ref":"#/components/parameters/access_key"},{"$ref":"#/components/parameters/url"},{"$ref":"#/components/parameters/render_js"},{"$ref":"#/components/parameters/keep_headers"},{"$ref":"#/components/parameters/proxy_location"},{"$ref":"#/components/parameters/premium_proxy"}],"responses":{"200":{"description":"Successful fetch — the API returns the raw target response (usually HTML). If you enabled header forwarding (`keep_headers=1`), HTTP headers forwarded from the target will also be returned in the API response.\n","content":{"text/html":{"schema":{"type":"string","description":"Raw HTML/text body returned from the target URL (as a string)."},"examples":{"minimal":{"summary":"Example HTML response (abbreviated)","value":"<!DOCTYPE html><html><head>...</head><body>...target HTML...</body></html>"}}},"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — missing/invalid parameters (e.g. missing `url`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}},"post":{"summary":"Basic Scrape (POST)","operationId":"scrapePost","description":"Method variant of `GET /scrape`. The target `url` (query parameter) is fetched using HTTP POST, and the request body is forwarded to the target byte-for-byte with its original `Content-Type`. Any content type is forwarded, including ones the API does not interpret (`application/xml`, `multipart/form-data`, binary payloads). Accepts the same query parameters as the GET operation.\n","requestBody":{"$ref":"#/components/requestBodies/ScrapeForwardedBody"},"parameters":[{"$ref":"#/components/parameters/access_key"},{"$ref":"#/components/parameters/url"},{"$ref":"#/components/parameters/render_js"},{"$ref":"#/components/parameters/keep_headers"},{"$ref":"#/components/parameters/proxy_location"},{"$ref":"#/components/parameters/premium_proxy"}],"responses":{"200":{"description":"Target response (raw) or JSON error object when scraping fails.","content":{"application/json":{"schema":{"oneOf":[{"type":"string","description":"Raw response body returned from the target (if Content-Type other than JSON)."},{"$ref":"#/components/schemas/ApiError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error — missing/invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}},"put":{"summary":"Basic Scrape (PUT)","operationId":"scrapePut","description":"Method variant of `GET /scrape` using HTTP PUT. The target `url` is fetched using HTTP PUT, and the request body is forwarded to the target byte-for-byte with its original `Content-Type`. Any content type is forwarded, including ones the API does not interpret (`application/xml`, `multipart/form-data`, binary payloads). Accepts the same query parameters as the GET operation.\n","requestBody":{"$ref":"#/components/requestBodies/ScrapeForwardedBody"},"parameters":[{"$ref":"#/components/parameters/access_key"},{"$ref":"#/components/parameters/url"},{"$ref":"#/components/parameters/render_js"},{"$ref":"#/components/parameters/keep_headers"},{"$ref":"#/components/parameters/proxy_location"},{"$ref":"#/components/parameters/premium_proxy"}],"responses":{"200":{"description":"Target response (raw) or JSON error.","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Maintenance"}}}}},"components":{"securitySchemes":{"AccessKeyQuery":{"type":"apiKey","in":"query","name":"access_key","description":"Your Scrapestack API access key. Pass it as `?access_key=YOUR_KEY` in every request"}},"requestBodies":{"ScrapeForwardedBody":{"required":false,"description":"Forwarded to the target byte-for-byte with its original `Content-Type`. Any content type is accepted, including ones the API does not itself interpret (`application/xml`, `multipart/form-data`, binary payloads).","content":{"*/*":{"schema":{"type":"string","format":"binary","description":"Raw request body, relayed to the target unchanged."}}}}},"parameters":{"access_key":{"name":"access_key","in":"query","required":true,"description":"Your Scrapestack API Access Key. Required on all requests.","schema":{"type":"string"},"example":"YOUR_ACCESS_KEY"},"url":{"name":"url","in":"query","required":true,"description":"Target URL to fetch. Must be url-encoded if it contains special characters. Example: `https://example.com/page`.","schema":{"type":"string","format":"uri"},"example":"https://apple.com"},"render_js":{"name":"render_js","in":"query","required":false,"description":"Set to `1` to enable JavaScript rendering (headless Chrome). Default `0` (off). The option must be used together with `premium_proxy` which is available on the Premium plan.\n","schema":{"type":"integer","enum":[0,1]},"example":1},"keep_headers":{"name":"keep_headers","in":"query","required":false,"description":"If set to `1`, custom HTTP request headers you include in your request will be forwarded to the target and returned with the API response. Unsupported header names: `content-encoding`, `content-length`. Default: `0`.\n","schema":{"type":"integer","enum":[0,1]},"example":1},"proxy_location":{"name":"proxy_location","in":"query","required":false,"description":"Two-letter country code used to geotarget the scraping request (for example `au`, `us`, `de`). Supported countries differ between standard (datacenter) and premium (residential) proxies; see the provider's download lists for exact codes.\n","schema":{"type":"string","minLength":2,"maxLength":2},"example":"au"},"premium_proxy":{"name":"premium_proxy","in":"query","required":false,"description":"Set to `1` to enable premium (residential) proxies (recommended when scraping anti-bot sites). Premium proxy usage is subject to plan restrictions and **each premium proxy request counts as 25 API requests** for billing. Default: `0`.\n","schema":{"type":"integer","enum":[0,1]},"example":1}},"schemas":{"ApiError":{"type":"object","description":"Standard error response when scraping fails.","properties":{"success":{"type":"boolean","description":"Indicates overall success (false for errors).","example":false},"error":{"type":"object","description":"Error detail object.","properties":{"code":{"type":"integer","description":"Numeric error code (see Scrapestack docs).","example":105},"type":{"type":"string","description":"Short machine-readable error type.","example":"scrape_request_failed"},"info":{"type":["string","null"],"description":"Optional human-friendly extra info (when available).","example":"Target responded with 403 Forbidden"}},"required":["code","type"]}},"required":["success","error"]},"SubscriptionError":{"type":"object","description":"Returned with HTTP 401 when the request uses an option the current subscription does not cover — most commonly `render_js`, which requires `premium_proxy` (Premium plan and above).\n","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"unauthorized"},"status":{"type":"integer","description":"HTTP status code (401).","example":401},"message":{"type":"string","description":"Human-readable explanation of the missing entitlement.","example":"Your subscription does not support JavaScript rendering. The render_js option requires premium_proxy, which is not included in your current plan. You must be on Premium plan or above to use premium_proxy."}},"required":["code","status","message"]}},"required":["error"]},"ValidationError":{"type":"object","description":"Returned with HTTP 422 when request parameters fail validation (see src/validations/scrape-validator.js). Uses the same error envelope as every other scrapestack error (`ApiError`): a single failure is reported, and when several parameters are invalid the first one in validation order wins (a missing `url` outranks an invalid one, and `url` outranks the options).\n\nCodes: `210` missing_url, `211` invalid_url (also returned when a Google target is requested without `premium_proxy`), `212` invalid_proxy_location, `214` invalid_render_js, `215` invalid_keep_headers, `216` invalid_premium_proxy.\n","properties":{"success":{"type":"boolean","description":"Always `false` for errors.","example":false},"error":{"type":"object","properties":{"code":{"type":"integer","description":"Numeric scrapestack error code (210-212, 214-216).","example":210},"type":{"type":"string","description":"Short machine-readable error type.","example":"missing_url"},"info":{"type":"string","description":"Human-readable explanation of the validation failure.","example":"You have not specified a valid URL. Please try again or refer to the API documentation available at https://scrapestack.com/documentation."}},"required":["code","type"]}},"required":["success","error"]}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"account_on_hold":{"summary":"account_on_hold","value":{"success":false,"error":{"code":107,"type":"account_on_hold","info":"Your account currently has open invoices and API has been automatically disabled. Please settle your open balance or downgrade to the Free Plan to restore API access. [Support: support@apilayer.com]"}}},"invalid_access_key":{"summary":"invalid_access_key","value":{"success":false,"error":{"code":101,"type":"invalid_access_key","info":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}},"missing_access_key":{"summary":"missing_access_key","value":{"success":false,"error":{"code":101,"type":"missing_access_key","info":"You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]"}}},"inactive_user":{"summary":"inactive_user","value":{"success":false,"error":{"code":102,"type":"inactive_user","info":"Permission denied - User not active."}}}}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"https_access_restricted":{"summary":"https_access_restricted","value":{"success":false,"error":{"code":105,"type":"https_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support HTTPS Encryption."}}},"function_access_restricted":{"summary":"function_access_restricted","value":{"success":false,"error":{"code":105,"type":"function_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support this API Function."}}},"api_access_blocked":{"summary":"api_access_blocked","value":{"success":false,"error":{"code":104,"type":"api_access_blocked","info":"Your API access has been temporarily disabled. Please upgrade your Subscription Plan or contact support."}}}}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"invalid_api_function":{"summary":"invalid_api_function","value":{"success":false,"error":{"code":103,"type":"invalid_api_function","info":"This API Function does not exist."}}},"404_not_found":{"summary":"404_not_found","value":{"success":false,"error":{"code":404,"type":"404_not_found","info":"404 - The requested resource could not be found. Please try again or contact support."}}}}}}},"RateLimitReached":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"usage_limit_reached":{"summary":"usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"usage_limit_reached","info":"Your monthly usage limit has been reached. Please upgrade your Subscription Plan."}}},"daily_usage_limit_reached":{"summary":"daily_usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"daily_usage_limit_reached","info":"Your daily usage limit has been reached. Please try again tomorrow or upgrade your subscription plan."}}},"fair_use_limit_reached":{"summary":"fair_use_limit_reached","value":{"success":false,"error":{"code":104,"type":"fair_use_limit_reached","info":"Your fair use limit has been reached. [Please contact support: support@apilayer.com]"}}},"rate_limit_reached":{"summary":"rate_limit_reached","value":{"success":false,"error":{"code":106,"type":"rate_limit_reached","info":"You have exceeded the maximum rate limitation allowed on your subscription plan. Please refer to the \"Rate Limits\" section of the API Documentation for details. "}}}}}}},"InternalError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"internal_error":{"summary":"internal_error","value":{"success":false,"error":{"code":0,"type":"internal_error","info":"An error has occured. [Technical Support: support@apilayer.com]"}}}}}}},"Maintenance":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"maintenance_mode":{"summary":"maintenance_mode","value":{"success":false,"error":{"code":503,"type":"maintenance_mode","info":""}}}}}}}}}}