snoopscan-com Extract API

openapi: 3.2.0
info:
  title: SnoopScan Extract API
  description: 'Turn any public web page into clean markdown or structured JSON: scrape, crawl, map, search and extract. One bearer key for every endpoint.'
  version: 0.1.0
servers:
- url: https://api.snoopscan.com
tags:
- name: Extract
paths:
  /v1/extract:
    post:
      tags:
      - Extract
      summary: Extract Structured
      description: 'Extract JSON in your schema from up to 100 pages.


        Returns one result per URL: `{url, data, confidence, error}`. A page that

        fails, or lacks the fields, gets an `error` without failing the request.'
      operationId: extract_structured_v1_extract_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Extract Structured V1 Extract Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/search:
    post:
      tags:
      - Extract
      summary: Search
      description: Search the web. Add `scrapeOptions` to get each result's page content too.
      operationId: search_v1_search_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Search V1 Search Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ScrapeOptions:
      properties:
        formats:
          items:
            anyOf:
            - type: string
              enum:
              - markdown
              - html
              - rawHtml
              - links
              - media
              - summary
              - screenshot
              - json
              - network
            - $ref: '#/components/schemas/ScreenshotFormat'
            - $ref: '#/components/schemas/JsonFormat'
            - $ref: '#/components/schemas/ChangeTrackingFormat'
          type: array
          title: Formats
          description: 'What to return: `markdown`, `html`, `rawHtml`, `links`, `media`, `summary`, `screenshot`, or a `json` object carrying your schema. Ask for several in one call.'
        onlyMainContent:
          type: boolean
          title: Onlymaincontent
          description: Return the article and drop navigation, headers, footers and cookie banners. Turn it off to keep the whole page.
          default: true
        includeTags:
          items:
            type: string
          type: array
          title: Includetags
          description: CSS selectors to keep even when they sit outside the main content.
        excludeTags:
          items:
            type: string
          type: array
          title: Excludetags
          description: CSS selectors to drop before the page is read.
        maxAge:
          type: integer
          minimum: 0.0
          title: Maxage
          description: Serve a cached copy if one was taken within this many milliseconds. A cache hit costs nothing. Set `0` to force a fresh fetch.
          default: 0
        storeInCache:
          type: boolean
          title: Storeincache
          description: Keep this response in the cache so a later request can be served free.
          default: true
        waitFor:
          type: integer
          maximum: 120000.0
          minimum: 0.0
          title: Waitfor
          description: Milliseconds to wait after the page loads before reading it, for content that loads late. Renders the page in a browser, and is billed as a browser page.
          default: 0
        timeout:
          type: integer
          maximum: 300000.0
          minimum: 1000.0
          title: Timeout
          description: Give up on this request after this many milliseconds.
          default: 90000
        actions:
          items:
            oneOf:
            - $ref: '#/components/schemas/WaitAction'
            - $ref: '#/components/schemas/ClickAction'
            - $ref: '#/components/schemas/CaptchaCheckboxAction'
            - $ref: '#/components/schemas/WriteAction'
            - $ref: '#/components/schemas/PressAction'
            - $ref: '#/components/schemas/ScrollAction'
            - $ref: '#/components/schemas/ScreenshotAction'
            - $ref: '#/components/schemas/ScrapeAction'
            - $ref: '#/components/schemas/ExecuteJavascriptAction'
            discriminator:
              propertyName: type
              mapping:
                captchaCheckbox: '#/components/schemas/CaptchaCheckboxAction'
                click: '#/components/schemas/ClickAction'
                executeJavascript: '#/components/schemas/ExecuteJavascriptAction'
                press: '#/components/schemas/PressAction'
                scrape: '#/components/schemas/ScrapeAction'
                screenshot: '#/components/schemas/ScreenshotAction'
                scroll: '#/components/schemas/ScrollAction'
                wait: '#/components/schemas/WaitAction'
                write: '#/components/schemas/WriteAction'
          type: array
          title: Actions
          description: 'Steps to run in a browser before the page is read: click, type, scroll, wait or `captchaCheckbox`. A `captchaCheckbox` step needs `successSelector`.'
        captchaHandling:
          type: string
          enum:
          - auto
          - 'off'
          title: Captchahandling
          description: Click a challenge checkbox once if one appears. Set `off` to never click.
          default: auto
        captchaEvidence:
          type: boolean
          title: Captchaevidence
          description: Return screenshots from before and after an automatic checkbox click.
          default: false
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: Extra headers to send. `User-Agent` and other browser-identity headers are set for you and cannot be changed.
        mobile:
          type: boolean
          title: Mobile
          description: Read the page as a phone would see it.
          default: false
        location:
          anyOf:
          - $ref: '#/components/schemas/Location'
          - type: 'null'
          description: 'Fetch from a country, in its language, e.g. `{"country": "US"}`.'
        proxy:
          $ref: '#/components/schemas/ProxyMode'
          description: Leave on `auto` and the route is chosen for you.
          default: auto
        blockAssets:
          type: boolean
          title: Blockassets
          description: Skip images, fonts and media when the page is rendered in a browser. Faster.
          default: true
        removeBase64Images:
          type: boolean
          title: Removebase64Images
          description: Strip inline base64 images out of the returned markdown and HTML.
          default: true
        parsers:
          items:
            type: string
            const: pdf
          type: array
          title: Parsers
          description: Which document parsers may run, for example `pdf`.
      additionalProperties: false
      type: object
      title: ScrapeOptions
      description: 'How a page is fetched and what comes back: every /v1/scrape field except `url`.'
    Location:
      properties:
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
        languages:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Languages
      additionalProperties: false
      type: object
      required:
      - country
      title: Location
    WaitAction:
      properties:
        type:
          type: string
          const: wait
          title: Type
        milliseconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Milliseconds
        selector:
          anyOf:
          - type: string
          - type: 'null'
          title: Selector
      additionalProperties: false
      type: object
      required:
      - type
      title: WaitAction
    ProxyMode:
      type: string
      enum:
      - none
      - datacenter
      - residential
      - mobile
      - auto
      title: ProxyMode
    ClickAction:
      properties:
        type:
          type: string
          const: click
          title: Type
        selector:
          type: string
          title: Selector
      additionalProperties: false
      type: object
      required:
      - type
      - selector
      title: ClickAction
    ChangeTrackingFormat:
      properties:
        type:
          type: string
          const: changeTracking
          title: Type
        modes:
          items:
            type: string
            enum:
            - git-diff
            - json
          type: array
          title: Modes
      additionalProperties: false
      type: object
      required:
      - type
      title: ChangeTrackingFormat
    SearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: What to search for.
        limit:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Limit
          description: How many results, 1 to 50.
          default: 10
        sources:
          items:
            type: string
            enum:
            - web
            - news
            - images
          type: array
          title: Sources
          description: 'Which kinds of result: `web`, `news`, `images`.'
        location:
          anyOf:
          - $ref: '#/components/schemas/Location'
          - type: 'null'
          description: 'The country to search from, which changes the results, e.g. `{"country": "GB"}`.'
        scrapeOptions:
          anyOf:
          - $ref: '#/components/schemas/ScrapeOptions'
          - type: 'null'
          description: Also fetch every result page with these options. Each page fetched is charged like a scrape.
        place:
          anyOf:
          - type: string
          - type: 'null'
          title: Place
          description: Where the searcher is standing, in free text, e.g. "Austin, Texas, United States". Finer than `location`.
        language:
          anyOf:
          - type: string
            maxLength: 8
            minLength: 2
          - type: 'null'
          title: Language
          description: The language results should be in, e.g. `en`.
        device:
          anyOf:
          - type: string
            enum:
            - desktop
            - mobile
          - type: 'null'
          title: Device
          description: '`desktop` or `mobile`. Mobile results can differ from desktop ones.'
        freshness:
          anyOf:
          - type: string
            enum:
            - hour
            - day
            - week
            - month
            - year
          - type: 'null'
          title: Freshness
          description: Only results from the last `hour`, `day`, `week`, `month` or `year`.
        safeSearch:
          anyOf:
          - type: string
            enum:
            - 'off'
            - moderate
            - strict
          - type: 'null'
          title: Safesearch
          description: '`off`, `moderate` or `strict`.'
        page:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Page
          description: Which page of results, starting at 1.
          default: 1
        autoCorrect:
          type: boolean
          title: Autocorrect
          description: Set `false` to search the query exactly as typed, e.g. a part number or a brand name.
          default: true
      additionalProperties: false
      type: object
      required:
      - query
      title: SearchRequest
      description: Search the web. Filters after `location` are optional; when set, every result matches.
    ModelSpec:
      properties:
        provider:
          type: string
          enum:
          - anthropic
          - openai
          title: Provider
        apiKey:
          type: string
          maxLength: 300
          minLength: 8
          title: Apikey
        name:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Name
      additionalProperties: false
      type: object
      required:
      - provider
      - apiKey
      title: ModelSpec
      description: Your own model provider and key for /v1/extract. Used for this request only, never stored.
    ExecuteJavascriptAction:
      properties:
        type:
          type: string
          const: executeJavascript
          title: Type
        script:
          type: string
          title: Script
      additionalProperties: false
      type: object
      required:
      - type
      - script
      title: ExecuteJavascriptAction
    JsonFormat:
      properties:
        schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Schema
          description: Your own JSON Schema for the fields you want. Give this or `template`, not both.
        template:
          anyOf:
          - type: string
          - type: 'null'
          title: Template
          description: A named template instead of a schema — `product`, `article`, `jobPosting` and more. GET /v1/templates lists them with their fields.
        type:
          type: string
          const: json
          title: Type
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
      additionalProperties: false
      type: object
      required:
      - type
      title: JsonFormat
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExtractRequest:
      properties:
        schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Schema
          description: Your own JSON Schema for the fields you want. Give this or `template`, not both.
        template:
          anyOf:
          - type: string
          - type: 'null'
          title: Template
          description: A named template instead of a schema — `product`, `article`, `jobPosting` and more. GET /v1/templates lists them with their fields.
        urls:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 1
          title: Urls
          description: The pages to extract from, 1 to 100. Each page gets its own result.
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Plain-language guidance on what to pick out, e.g. "the cheapest paid plan".
        scrapeOptions:
          $ref: '#/components/schemas/ScrapeOptions'
          description: 'How each page is fetched: the same options /v1/scrape takes.'
        model:
          anyOf:
          - $ref: '#/components/schemas/ModelSpec'
          - type: 'null'
          description: Your own model provider and key. Model calls are billed to your key, at no credit cost.
      additionalProperties: false
      type: object
      required:
      - urls
      title: ExtractRequest
    CaptchaCheckboxAction:
      properties:
        type:
          type: string
          const: captchaCheckbox
          title: Type
        frameSelector:
          type: string
          title: Frameselector
          default: iframe[src*="/recaptcha/"][src*="/anchor"]
        selector:
          type: string
          title: Selector
          default: '#recaptcha-anchor'
        successSelector:
          type: string
          minLength: 1
          title: Successselector
        timeoutMs:
          type: integer
          maximum: 15000.0
          minimum: 500.0
          title: Timeoutms
          default: 8000
        captureEvidence:
          type: boolean
          title: Captureevidence
          description: Return a screenshot from before and after the click.
          default: false
      additionalProperties: false
      type: object
      required:
      - type
      - successSelector
      title: CaptchaCheckboxAction
      description: Click a challenge checkbox once, then wait for `successSelector` to appear.
    WriteAction:
      properties:
        type:
          type: string
          const: write
          title: Type
        selector:
          type: string
          title: Selector
        text:
          type: string
          title: Text
      additionalProperties: false
      type: object
      required:
      - type
      - selector
      - text
      title: WriteAction
    ScreenshotAction:
      properties:
        type:
          type: string
          const: screenshot
          title: Type
        fullPage:
          type: boolean
          title: Fullpage
          default: false
      additionalProperties: false
      type: object
      required:
      - type
      title: ScreenshotAction
    PressAction:
      properties:
        type:
          type: string
          const: press
          title: Type
        key:
          type: string
          title: Key
      additionalProperties: false
      type: object
      required:
      - type
      - key
      title: PressAction
    ScrapeAction:
      properties:
        type:
          type: string
          const: scrape
          title: Type
      additionalProperties: false
      type: object
      required:
      - type
      title: ScrapeAction
    ScrollAction:
      properties:
        type:
          type: string
          const: scroll
          title: Type
        direction:
          type: string
          enum:
          - up
          - down
          title: Direction
          default: down
        amount:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Amount
          default: 1
      additionalProperties: false
      type: object
      required:
      - type
      title: ScrollAction
    ScreenshotFormat:
      properties:
        type:
          type: string
          const: screenshot
          title: Type
        fullPage:
          type: boolean
          title: Fullpage
          default: false
        quality:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Quality
          default: 80
      additionalProperties: false
      type: object
      required:
      - type
      title: ScreenshotFormat
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError