openapi: 3.0.0
info:
  title: ScrapeNinja Web Scraping API
  description: |-
    This is a high-performance web scraping API with smart retries and proxy rotation, with multiple proxy geos, and with two scraping engines under the hood: high performance engine with Chrome browser TLS fingerprint, but without JavaScript execution and real browser overhead; and real Chrome browser engine, with JS and CSS evaluation and screenshots, when high performance engine features are not enough.
    
    ScrapeNinja API is available on two marketplace platforms: RapidAPI and APIRoad.
    To get your API key, go to https://rapidapi.com/restyler/api/scrapeninja or https://apiroad.net/marketplace/apis/scrapeninja
    If you prefer to use APIRoad, you will need to replace API key name from `X-RapidAPI-Key` to `X-Apiroad-Key`.
  version: 1.0.0
servers:
  - url: https://scrapeninja.apiroad.net
  - url: https://scrapeninja.p.rapidapi.com
components:
  securitySchemes:
    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: header       # can be "header", "query" or "cookie"
      name: X-RapidAPI-Key  # name of the header, query parameter or cookie
security:
      - ApiKeyAuth: []
paths:
  /scrape:
    post:
      operationId: scrape
      summary: "/scrape: non-JS scraping"
      description: Use high-performance web scraping endpoint with Chrome browser TLS fingerprint, but without JavaScript execution and real browser overhead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - "url"
              properties:
                url:
                  type: string
                  description: URL to scrape
                  example: https://example.com
                headers:
                  type: array
                  items:
                    type: string
                  description: Custom headers to send with the request. By default, regular Chrome browser headers are sent to the target URL.
                  example: ["X-Header: some-random-header"]
                retryNum:
                  type: integer
                  description: Amount of attempts.
                  example: 1
                geo:
                  type: string
                  description: "Geo location for basic proxy pools (you can purchase premium ScrapeNinja proxies for wider country selection and higher proxy quality). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "eu"
                  default: "us"
                proxy:
                  type: string
                  description: "Premium or your own proxy URL (overrides `geo` field). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "http://user:pw@host:port"
                followRedirects:
                  type: integer
                  description: Follow redirects.
                  example: 0
                  default: 1
                timeout:
                  type: integer
                  description: Timeout per attempt, in seconds. Each retry will take [timeout] number of seconds.
                  example: 8
                  default: 10
                textNotExpected:
                  type: array
                  items:
                    type: string
                  description: Text which will trigger a retry from another proxy address.
                  example: ["random-captcha-text-which-might-appear"]
                statusNotExpected:
                  type: array
                  items:
                    type: integer
                  description: HTTP response statuses which will trigger a retry from another proxy address.
                  example: [403, 429]
                  default: [403, 502]
                extractor:
                  type: string
                  description: Custom JS function to extract JSON values from scraped HTML. Write&test your own extractor on https://scrapeninja.net/cheerio-sandbox/
                  example: "function(input, cheerio) {\n    let $ = cheerio.load(input);\n return $('h1.title').text(); } "
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: object
                    properties:
                      statusCode:
                        type: integer
                        example: 200
                      finalUrl:
                        type: string
                        example: https://example.com/url
                      headers:
                        type: array
                        items:
                          type: string
                        example: ["content-type: xxx", "header2: val2"]
                    required:
                      - statusCode
                      - finalUrl
                      - headers
                  body:
                    type: string
                    example: "<html><body><h1>Hello World!</h1></body></html>"
                    description: HTML body of the rendered page.
                    required:
                    - body

  /scrape-js:
    post:
      operationId: scrape-js
      summary: "/scrape-js: scraping with JS rendering"
      description: Launches real Chrome browser engine, use only when /scrape endpoint features are not enough.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - "url"
              type: object
              properties:
                url:
                  type: string
                  description: URL to scrape
                  example: https://example.com
                waitForSelector:
                  type: string
                  description: CSS selector to wait to appear in DOM tree before page is considered as loaded.
                  example: "h1.some-class"
                postWaitTime:
                  type: integer
                  description: Wait for specified amount of seconds after page load (from 1 to 12s). Use this only if ScrapeNinja failed to wait for required page elements automatically.
                  example: 5
                dumpIframe:
                  type: string
                  description: If some particular iframe needs to be dumped, specify its `name` HTML value in this argument. The ScrapeNinja JS renderer will wait for <iframe name="icims_content_iframe"> to appear in DOM, then use `waitForSelectorIframe` CSS selector to wait for iframe DOM elements to appear inside.
                  example: "icims_content_iframe"
                waitForSelectorIframe:
                  type: string
                  description: If `dumpIframe` is activated, this property allows to wait for CSS selector inside this iframe.
                  example: ".iCIMS_PagingBatch"
                extractorTargetIframe:
                  type: boolean
                  description: If `dumpIframe` is activated, this property allows to run JS extractor function against iframe HTML instead of running it against base body. This is only useful if `dumpIframe` is activated.
                  example: true
                headers:
                  type: array
                  items:
                    type: string
                  description: Custom headers to send with the request. By default, regular Chrome browser headers are sent to the target URL.
                  example: ["X-Header: some-random-header"]
                retryNum:
                  type: integer
                  description: Amount of attempts.
                  example: 1
                geo:
                  type: string
                  description: "Geo location for basic proxy pools (you can purchase premium ScrapeNinja proxies for wider country selection and higher proxy quality). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "eu"
                  default: "us"
                proxy:
                  type: string
                  description: "Premium or your own proxy URL (overrides `geo` field). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "http://user:pw@host:port"
                timeout:
                  type: integer
                  description: Timeout per attempt, in seconds. Each retry will take [timeout] number of seconds.
                  example: 8
                  default: 16
                textNotExpected:
                  type: array
                  items:
                    type: string
                  description: Text which will trigger a retry from another proxy address.
                  example: ["random-captcha-text-which-might-appear"]
                statusNotExpected:
                  type: array
                  items:
                    type: integer
                  description: HTTP response statuses which will trigger a retry from another proxy address.
                  example: [403, 429]
                  default: [403, 502]
                blockImages: 
                  type: boolean
                  description: Block images from loading. This will speed up page loading and reduce bandwidth usage.
                  example: true
                blockMedia:
                  type: boolean
                  description: Block (CSS, fonts) from loading. This will speed up page loading and reduce bandwidth usage.
                  example: true
                screenshot:
                  type: boolean
                  description: Take a screenshot of the page. Pass "false" to increase the speed of the request.
                  example: true
                catchAjaxHeadersUrlMask:
                  type: string
                  description: Useful to dump some XHR response. Pass URL mask here. For example, if you need to catch all requests to https://example.com/api/data.json, pass "api/data.json" here. In response, you will get new property `.info.catchedAjax` with the XHR response data - { url, method, headers[], body , status, responseHeaders{} }
                viewport:
                  type: object
                  description: Advanced. Set custom viewport size. By default, viewport size is 1920x1080.
                  properties:
                    width:
                      type: integer
                      example: 1920
                    height:
                      type: integer
                      example: 1080
                    deviceScaleFactor:
                      type: integer
                      example: 3
                    hasTouch:
                      type: boolean
                      example: false
                    isMobile:
                      type: boolean
                      example: false
                    isLandscape:
                      type: boolean
                      example: false

                extractor:
                  type: string
                  description: Custom JS function to extract JSON values from scraped HTML. Write&test your own extractor on https://scrapeninja.net/cheerio-sandbox/
                  example: "function(input, cheerio) {\n    let $ = cheerio.load(input);\n return $('h1.title').text(); } "
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: object
                    properties:
                      statusCode:
                        type: integer
                        example: 200
                      finalUrl:
                        type: string
                        example: https://example.com/url
                      catchedAjax:
                        type: object
                        properties:
                          url:
                            type: string
                            example: https://example.com/api/data.json
                          method:
                            type: string
                            example: GET
                          headers:
                            description: Array of request headers
                            type: array
                            items:
                              type: string
                            example: ["content-type: xxx", "header2: val2"]
                          body:
                            type: string
                            example: "<html><body><h1>Hello World!</h1></body></html>"
                          bodyIframe:
                            type: string
                            description: If `dumpIframe` is activated, this property contains iframe HTML.
                            example: "<html><body><h1>Iframe content</h1></body></html>"
                          status:
                            type: integer
                            example: 200
                          responseHeaders:
                            description: Object with response headers
                            type: object
                            example: {"content-type": "application/json"}
                      headers:
                        type: array
                        items:
                          type: string
                        example: ["content-type: xxx", "header2: val2"]
                    required:
                      - statusCode
                      - finalUrl
                      - headers
                      - screenshot
                      - pageCookies
                  body:
                    type: string
                    example: "<html><body><h1>Hello World!</h1></body></html>"
                    description: HTML body of the rendered page.
                    required:
                      - body
  /v2/scrape-js:
    post:
      operationId: scrape-js-v2
      summary: "/v2/scrape-js: scraping with JS rendering, new engine"
      description: "Launches real Chrome browser engine, better success rate for websites protected by Cloudflare, Datadome, Kasada, PermimeterX. ATTENTION: Only available <a href='https://scrapeninja.net/docs/getting-started/#subscription-via-apiroad-recommended-way'>via APIRoad!</a>"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - "url"
              type: object
              properties:
                url:
                  type: string
                  description: URL to scrape
                  example: https://example.com
                waitForSelector:
                  type: string
                  description: CSS selector to wait to appear in DOM tree before page is considered as loaded.
                  example: "h1.some-class"
                postWaitTime:
                  type: integer
                  description: Wait for specified amount of seconds after page load (from 1 to 12s). Use this only if ScrapeNinja failed to wait for required page elements automatically.
                  example: 5
                
                headers:
                  type: array
                  items:
                    type: string
                  description: Custom headers to send with the request. By default, regular Chrome browser headers are sent to the target URL.
                  example: ["X-Header: some-random-header"]
                retryNum:
                  type: integer
                  description: Amount of attempts.
                  example: 1
                geo:
                  type: string
                  description: "Geo location for basic proxy pools (you can purchase premium ScrapeNinja proxies for wider country selection and higher proxy quality). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "eu"
                  default: "us"
                proxy:
                  type: string
                  description: "Premium or your own proxy URL (overrides `geo` field). [Read more about ScrapeNinja proxy setup](https://scrapeninja.net/docs/proxy-setup/)"
                  example: "http://user:pw@host:port"
                timeout:
                  type: integer
                  description: Timeout per attempt, in seconds. Each retry will take [timeout] number of seconds.
                  example: 8
                  default: 16
                textNotExpected:
                  type: array
                  items:
                    type: string
                  description: Text which will trigger a retry from another proxy address.
                  example: ["random-captcha-text-which-might-appear"]
                statusNotExpected:
                  type: array
                  items:
                    type: integer
                  description: HTTP response statuses which will trigger a retry from another proxy address.
                  example: [403, 429]
                  default: [403, 502]
                blockImages: 
                  type: boolean
                  description: Block images from loading. This will speed up page loading and reduce bandwidth usage.
                  example: true
                blockMedia:
                  type: boolean
                  description: Block (CSS, fonts) from loading. This will speed up page loading and reduce bandwidth usage.
                  example: true
                screenshot:
                  type: boolean
                  description: Take a screenshot of the page. Pass "false" to increase the speed of the request.
                  example: true
                

                extractor:
                  type: string
                  description: Custom JS function to extract JSON values from scraped HTML. Write&test your own extractor on https://scrapeninja.net/cheerio-sandbox/
                  example: "function(input, cheerio) {\n    let $ = cheerio.load(input);\n return $('h1.title').text(); } "
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: object
                    properties:
                      statusCode:
                        type: integer
                        example: 200
                      finalUrl:
                        type: string
                        example: https://example.com/url
                      catchedAjax:
                        type: object
                        properties:
                          url:
                            type: string
                            example: https://example.com/api/data.json
                          method:
                            type: string
                            example: GET
                          headers:
                            description: Array of request headers
                            type: array
                            items:
                              type: string
                            example: ["content-type: xxx", "header2: val2"]
                          body:
                            type: string
                            example: "<html><body><h1>Hello World!</h1></body></html>"
                          bodyIframe:
                            type: string
                            description: If `dumpIframe` is activated, this property contains iframe HTML.
                            example: "<html><body><h1>Iframe content</h1></body></html>"
                          status:
                            type: integer
                            example: 200
                          responseHeaders:
                            description: Object with response headers
                            type: object
                            example: {"content-type": "application/json"}
                      headers:
                        type: array
                        items:
                          type: string
                        example: ["content-type: xxx", "header2: val2"]
                    required:
                      - statusCode
                      - finalUrl
                      - headers
                      - screenshot
                      - pageCookies
                  body:
                    type: string
                    example: "<html><body><h1>Hello World!</h1></body></html>"
                    description: HTML body of the rendered page.
                    required:
                      - body