> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List endpoints

> List the endpoints with their prices, input schemas and examples. Send one request and get JSON back. Examples in cURL, TypeScript and Python.

> [!NOTE]
>
> Needs no API key.

## Price

Free, and needs no key.

See [Pricing](https://docs.stophy.dev/account/pricing.md).

```bash cURL theme={null}
curl https://api.stophy.dev/v1/endpoints
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/endpoints");
console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api.stophy.dev/v1/endpoints",
)
print(response.json())
```

```json 200 theme={null}
{
  "sources": [
    {
      "id": "web",
      "name": "Web",
      "summary": "Search the web and read any public page as markdown, HTML, links, a screenshot or JSON",
      "kind": "site"
    }
  ],
  "endpoints": [
    {
      "id": "search",
      "title": "Search",
      "summary": "Search the web, news, images, scholarly papers and YouTube videos in one call",
      "bestWhen": "Best when you want web results, news, images or all three at once, grouped by type, with the page text of the top web…",
      "method": "POST",
      "path": "/v1/search",
      "credits": 1,
      "maxCredits": 2010,
      "costUsd": 0.001,
      "maxCostUsd": 4.02,
      "pricing": "$0.001 for each 10 results from each source and each research or videos list ($1 per 1,000 searches of up to 10…",
      "keyless": true,
      "cacheTtlSeconds": 0,
      "input": {
        "type": "object",
        "properties": {
          "query": {
            "description": "What to search for, up to 500 characters. Search operators work in web results: quotes for an exact phrase, -word,…",
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "sources": {
            "description": "What to search: web, news, images. Each is a string or {type}. Default web, or none when categories asks for research…",
            "minItems": 1,
            "maxItems": 5,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "web",
                    "news",
                    "images"
                  ]
                }
              ]
            }
          },
          "categories": {
            "description": "pdf: web results that are PDF files. research: scholarly papers, in a research list, ranked by relevance then…",
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "research",
                    "pdf",
                    "videos"
                  ]
                }
              ]
            }
          },
          "maxAge": {
            "description": "Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 15 minutes for news and 1 hour…",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "limit": {
            "description": "Most results to return for each source. Default 10, or 5 when scrapeOptions has formats, which reads every web and…",
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "tbs": {
            "description": "Time filter: qdr:d, qdr:w, qdr:m or qdr:y, or cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY, plus sbd:1, like sbd:1,qdr:w.…",
            "type": "string",
            "minLength": 1
          },
          "location": {
            "description": "Where to search from, like Germany or San Francisco,California,United States. The last part is the country and…",
            "type": "string",
            "minLength": 1
          },
          "country": {
            "description": "Two-letter country to search from, like us. uk is read as gb. Image results are always US.",
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "lang": {
            "description": "Two-letter language for web results, like de. It steers which pages come back; some results can still be in other…",
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "includeDomains": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excludeDomains": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "safe": {
            "description": "Hide explicit web, news and image results when true.",
            "type": "boolean"
          },
          "timeout": {
            "description": "Milliseconds to wait for the sources, from 1,000 to 120,000; more is read as 120,000. Default 60,000. A source that…",
            "type": "integer",
            "minimum": 1000,
            "maximum": 9007199254740991
          },
          "ignoreInvalidURLs": {
            "default": false,
            "description": "Leave out results whose address cannot be read as a page.",
            "type": "boolean"
          },
          "highlights": {
            "default": false,
            "description": "Off by default. With true, a web result whose page we already hold gets the passages that best match the query as its…",
            "type": "boolean"
          },
          "scrapeOptions": {
            "description": "With formats, reads each web and news result, as many as limit asks for, within timeout, and fills each web result's…",
            "type": "object",
            "properties": {
              "formats": {
                "description": "What to return: markdown (clean page text), summary (a short summary of the page), html (the cleaned page), rawHtml…",
                "default": [
                  "markdown"
                ],
                "minItems": 1,
                "maxItems": 20,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "markdown",
                        "summary",
                        "html"
                      ]
                    }
                  ]
                }
              },
              "onlyMainContent": {
                "default": true,
                "description": "Keep only the page's main content, without menus, headers, footers and ads.",
                "type": "boolean"
              },
              "onlyCleanContent": {
                "description": "Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share…",
                "type": "boolean"
              },
              "includeTags": {
                "description": "Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent…",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "excludeTags": {
                "description": "Remove the parts of the page that match these CSS selectors, such as .comments.",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "maxAge": {
                "description": "Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose…",
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "minAge": {
                "description": "Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts…",
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "headers": {
                "description": "Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or…",
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9-]{1,64}$"
                },
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 2000,
                  "pattern": "^[\\t\\x20-\\x7e]*$"
                }
              },
              "waitFor": {
                "description": "Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an…",
                "type": "integer",
                "minimum": 0,
                "maximum": 60000
              },
              "mobile": {
                "description": "Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.",
                "type": "boolean"
              },
              "skipTlsVerification": {
                "description": "Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private…",
                "type": "boolean"
              },
              "timeout": {
                "default": 30000,
                "description": "How long to keep trying, in milliseconds, from 1 second to 5 minutes; 30 seconds by default. A page that needs a…",
                "type": "integer",
                "minimum": 1000,
                "maximum": 300000
              },
              "parsers": {
                "description": "Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same…",
                "minItems": 1,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "const": "pdf"
                    }
                  ]
                }
              },
              "actions": {
                "description": "Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60…",
                "minItems": 1,
                "maxItems": 50,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "const": "wait"
                        },
                        "milliseconds": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 60000
                        }
                      },
                      "required": [
                        "type",
                        "milliseconds"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "location": {
                "description": "Where to read the page from. The default is the United States.",
                "type": "object",
                "properties": {
                  "country": {
                    "description": "Two-letter country code to read the page from, such as DE or JP.",
                    "type": "string"
                  },
                  "languages": {
                    "description": "Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is…",
                    "minItems": 1,
                    "maxItems": 5,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
                    }
                  }
                },
                "additionalProperties": false
              },
              "removeBase64Images": {
                "description": "Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep…",
                "type": "boolean"
              },
              "blockAds": {
                "description": "Ads and trackers are not loaded when a page runs in a browser. Send false to load them.",
                "type": "boolean"
              },
              "fastMode": {
                "description": "Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or…",
                "type": "boolean"
              },
              "proxy": {
                "description": "auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the…",
                "type": "string",
                "enum": [
                  "auto",
                  "basic",
                  "enhanced"
                ]
              },
              "storeInCache": {
                "default": true,
                "description": "Send false to neither read nor keep a stored copy of this page.",
                "type": "boolean"
              },
              "lockdown": {
                "description": "Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no…",
                "type": "boolean"
              },
              "checkPromptInjection": {
                "description": "Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that…",
                "type": "boolean"
              },
              "redactPII": {
                "description": "Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers,…",
                "anyOf": [
                  {
                    "type": "boolean"
                  }
                ]
              },
              "profile": {
                "description": "Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for…",
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "description": "A name you choose, such as shop-login. Calls with the same name share state."
                  },
                  "saveChanges": {
                    "default": true,
                    "description": "Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with…",
                    "type": "boolean"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "zeroDataRetention": {
                "default": false,
                "description": "Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Adds $2 per…",
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "query"
        ],
        "$defs": {
          "__schema0": {
            "anyOf": [
              {
                "type": "string"
              }
            ]
          },
          "__schema1": {
            "anyOf": [
              {
                "type": "string"
              }
            ]
          },
          "__schema2": {
            "anyOf": [
              {
                "type": "string"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "example": {
        "query": "nvidia earnings",
        "sources": [
          "web",
          "news"
        ],
        "limit": 5
      }
    }
  ]
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/endpoints
openapi: 3.1.0
info:
  title: Stophy API
  version: '1'
  description: >-
    Each operation shows its method and its input: a JSON object body, path and
    query parameters, or a file upload.


    Responses leave out empty values: null, empty strings, empty objects and
    empty nested lists are not sent.


    Text comes back whole. To get shorter responses, add
    ?maxTextLength=<characters> to the URL. Every text value longer than that is
    cut and ends with …. A screenshot is never cut, and a page whose text was
    cut has isTruncated set to true.


    x-cost-usd is what one call costs, in dollars. Every call costs the same,
    whatever it returns, unless an operation's description says it costs per 10
    results, or per hour of audio. Then x-cost-usd is the lowest price and
    x-cost-usd-max the most one call can cost. Where an operation takes limit,
    send it to return fewer results and pay for fewer.


    When a response has a cursor, send it back unchanged with the same input to
    get the next page. When it has a page, send the next page number.
servers:
  - url: https://api.stophy.dev
security:
  - apiKey: []
paths:
  /v1/endpoints:
    get:
      summary: List the endpoints with their prices, input schemas and examples.
      description: Free, and needs no key.
      operationId: listEndpoints
      responses:
        '200':
          description: The endpoints and the sources they read.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    readOnly: true
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        summary:
                          type: string
                        kind:
                          type: string
                          enum:
                            - site
                            - aiAnswers
                      required:
                        - id
                        - name
                        - summary
                        - kind
                  endpoints:
                    readOnly: true
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          pattern: ^[a-z0-9]+(?:\.[a-zA-Z0-9-]+)*$
                        title:
                          type: string
                        summary:
                          type: string
                        bestWhen:
                          anyOf:
                            - type: string
                            - type: 'null'
                        method:
                          type: string
                          const: POST
                        path:
                          type: string
                          pattern: ^\/v1\/.*
                        credits:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        maxCredits:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        costUsd:
                          type: number
                          minimum: 0
                        maxCostUsd:
                          type: number
                          minimum: 0
                        pricing:
                          anyOf:
                            - type: string
                            - type: 'null'
                        keyless:
                          type: boolean
                        cacheTtlSeconds:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        input:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            $ref: '#/components/schemas/listEndpoints.26.schema0'
                        example:
                          anyOf:
                            - type: object
                              propertyNames:
                                type: string
                              additionalProperties:
                                $ref: '#/components/schemas/listEndpoints.26.schema0'
                            - type: 'null'
                      required:
                        - id
                        - title
                        - summary
                        - bestWhen
                        - method
                        - path
                        - credits
                        - maxCredits
                        - pricing
                        - keyless
                        - cacheTtlSeconds
                        - input
                        - example
                required:
                  - sources
                  - endpoints
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      security: []
components:
  schemas:
    listEndpoints.26.schema0:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/listEndpoints.26.schema0'
        - type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/listEndpoints.26.schema0'
    Error:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          const: false
        error:
          type: string
          description: What went wrong and what to do next.
        code:
          type: string
          enum:
            - apiKeyRequired
            - busy
            - checkRunning
            - cliSessionCompleted
            - cliSessionExists
            - cliSessionNotFound
            - forbidden
            - freeLimit
            - insufficientCredits
            - internalError
            - inviteClaimed
            - inviteDisabled
            - inviteExpired
            - inviteUsedUp
            - invalidCliSession
            - invalidCliVerifier
            - invalidRequest
            - jobFinished
            - methodNotAllowed
            - notFound
            - payloadTooLarge
            - profileBusy
            - profileTooLarge
            - prohibitedPermission
            - promptInjectionDetected
            - rateLimited
            - sourceChanged
            - sourceRefused
            - siteNotRead
            - sourceTimeout
            - sourceUnavailable
            - unauthorized
            - unsupportedMediaType
        retryable:
          type: boolean
          description: true when trying again can help.
        retryAfterSeconds:
          type: integer
        requestId:
          type: string
        requiredCredits:
          type: number
          description: >-
            Older field: the most the call can cost, in $0.002 steps. Sent when
            the balance is too low.
        availableCredits:
          type: number
          description: 'Older field: the balance in $0.002 steps. Sent with requiredCredits.'
        requiredUsd:
          type: number
          description: >-
            The most the call can cost, in dollars. Sent when the balance is too
            low.
        availableUsd:
          type: number
          description: What is left on the account, in dollars. Sent with requiredUsd.
        billingUrl:
          type: string
          description: Where to add money. Sent with requiredUsd.
        signupUrl:
          type: string
          const: https://stophy.dev/signup
          description: >-
            Where a person gets a key. Sent with apiKeyRequired, freeLimit and
            an invalid key.
        signup:
          type: string
          const: POST https://api.stophy.dev/v1/signup
          description: >-
            The call that gets an agent a key with no human. Sent next to
            signupUrl.
  responses:
    Error:
      description: The request failed. Retry-After says when trying again can help.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RequestId:
      description: The request id. Quote it when you report a problem.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.