Asked Thrice Scans API

openapi: 3.2.0
info:
  title: Asked Thrice Scans API
  version: 2.0.0
  summary: 'Scan a site: who ChatGPT, Gemini and Claude recommend for its customers'' questions, and which pages they cite.'
  description: 'The HTTP surface of askedthrice.com. A scan reads one site, writes six questions its customers would ask, asks them to ChatGPT, Gemini and Claude with web search on, and returns how many answers name the business, who they recommend instead, every page they cited and one step for each page where the business can get listed.


    **Scans are paid before they run.** One scan costs USD 15 and five cost USD 49 (in Argentina, ARS 19.000 and ARS 65.000 through Mercado Pago). Starting a scan or buying one needs the session cookie of an account signed in on the site: there is no API key and no free tier. Reading a finished scan by its id needs nothing.


    **Errors are always JSON**, including 404s for paths that do not exist. Every error body carries `error` (human sentence), `code` (stable identifier to branch on), `hint` (what to do next) and `docs`.


    Human documentation: https://askedthrice.com/developers · Pricing: https://askedthrice.com/pricing'
  contact:
    name: Asked Thrice support
    email: jorgenahuelsoria@gmail.com
    url: https://askedthrice.com/contact
  termsOfService: https://askedthrice.com/terms
  license:
    name: Proprietary
    url: https://askedthrice.com/terms
servers:
- url: https://askedthrice.com
  description: Production
tags:
- name: Scans
  description: Start a paid scan, read its result, and buy scans.
paths:
  /api/scan:
    post:
      operationId: startScan
      summary: Start a scan of one site, charging one scan from the account
      description: 'Charges one scan from the signed-in account and starts the scan in the background. Answers 202 with the scan `id` right away; poll `getScan` until `status` is `done` or `failed`. A scan takes about a minute.


        A scan that fails, or stops answering for six minutes, goes back to the account. Accounts that hold the lifetime pass sold until 2026-10-29 are not charged.


        Limits: 10 scans per hour and 30 per day per account.'
      tags:
      - Scans
      security:
      - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
            examples:
              site:
                summary: A bare domain
                value:
                  website: askedthrice.com
      responses:
        '202':
          description: The scan was charged and started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStarted'
        '400':
          description: 'The site is missing or is not a public address. Code: `invalid_website`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'No signed-in account. Code: `sign_in`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'The account has no scans left. Besides the error fields, the body carries the packs for sale in the caller''s currency. Code: `no_credits`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'This site or account is not accepted. Code: `blocked`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'Hourly or daily limit for the account. Code: `rate_limited`.'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying. Always present on 429.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: 'Scans are paused, or the charge could not be written. Codes: `budget`, `budget_unavailable`, `charge_failed`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    get:
      operationId: getScanAllowance
      summary: How many scans the signed-in account has left, and the prices
      description: Returns whether a session is present, the scans left on the account, whether it holds the lifetime pass, and the packs for sale in the caller's currency (pesos in Argentina, USD elsewhere). Without a session it still returns the prices.
      tags:
      - Scans
      security:
      - {}
      - sessionCookie: []
      responses:
        '200':
          description: The allowance and the packs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanAllowance'
        '500':
          description: 'The balance could not be read. Code: `server_error`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/scan/{scanId}:
    parameters:
    - name: scanId
      in: path
      required: true
      description: The `id` returned by `startScan`.
      schema:
        type: string
        format: uuid
    get:
      operationId: getScan
      summary: 'Read a scan: its stage while it runs, the full result when it is done'
      description: 'Never spends anything and needs no account: the id is the share link of the scan. While `status` is `running`, `stage` says which step it is on; when `done`, `result` carries the questions, every answer with its citations, who was named, the cited pages and the steps.'
      tags:
      - Scans
      security:
      - {}
      responses:
        '200':
          description: The scan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '404':
          description: 'No scan with that id. Code: `scan_not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/checkout/scan:
    post:
      operationId: buyScans
      summary: Open a payment page for one scan or a pack of five
      description: 'Returns the URL of a hosted payment page: Mercado Pago in pesos for callers in Argentina, Polar in USD elsewhere. Open it in a browser; after paying, the provider sends the buyer back to `next` and the scans are credited to the account by webhook within seconds.'
      tags:
      - Scans
      security:
      - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: The payment page.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          description: '`scans` is not 1 or 5. Code: `invalid_pack`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'No signed-in account. Code: `sign_in`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: 'The payment provider did not answer. Code: `checkout_failed`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ScanAllowance:
      type: object
      title: ScanAllowance
      required:
      - signedIn
      - pass
      - balance
      - currency
      - packs
      properties:
        signedIn:
          type: boolean
        pass:
          type: boolean
          description: True when the account holds the lifetime pass, which scans without charging.
        balance:
          type: integer
          description: Scans left on the account.
        currency:
          type: string
          enum:
          - ars
          - usd
        packs:
          type: array
          items:
            $ref: '#/components/schemas/Pack'
    ApiError:
      type: object
      title: ApiError
      description: The shape of every error from this API, including 404s for paths that do not exist. Branch on `code`, show `error`, act on `hint`.
      required:
      - error
      - code
      - hint
      - docs
      properties:
        error:
          type: string
          description: One sentence, safe to show to a person.
        code:
          type: string
          description: Stable identifier for this failure. Branch on this one; the wording of `error` can change.
          examples:
          - sign_in
          - no_credits
          - invalid_website
          - endpoint_not_found
        hint:
          type: string
          description: 'What to do next: sign in, buy scans, fix a field, or wait.'
        docs:
          type: string
          format: uri
          description: Human documentation for this API.
    ScanStarted:
      type: object
      title: ScanStarted
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: Pass this to `getScan`.
    Pack:
      type: object
      title: Pack
      required:
      - scans
      - price
      properties:
        scans:
          type: integer
          enum:
          - 1
          - 5
        price:
          type: string
          description: Formatted price with its currency code, e.g. `USD 15` or `ARS 19.000`.
    Scan:
      type: object
      title: Scan
      required:
      - id
      - status
      - domain
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - running
          - done
          - failed
        stage:
          type:
          - string
          - 'null'
          enum:
          - reading_site
          - asking
          - analyzing
          - done
          - null
        brand:
          type:
          - string
          - 'null'
        domain:
          type: string
        result:
          type: object
          additionalProperties: true
          description: 'Present when `status` is `done`: the profile read from the site, the questions, every answer with its citations, the businesses named, the cited sources and the steps.'
    CheckoutRequest:
      type: object
      title: CheckoutRequest
      required:
      - scans
      properties:
        scans:
          type: integer
          enum:
          - 1
          - 5
          description: How many scans to buy.
        next:
          type: string
          description: Same-site path to return to after paying. `paid=1` is appended on success.
          default: /
    ScanRequest:
      type: object
      title: ScanRequest
      required:
      - website
      properties:
        website:
          type: string
          description: The site to scan. A bare domain is accepted and normalised to https. Must be a public host. Brand, market, language and questions are read from the site.
          examples:
          - askedthrice.com
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: The session cookie set by signing in on the site. There is no way to obtain one from this API.
externalDocs:
  description: Asked Thrice developer and agent resources
  url: https://askedthrice.com/developers