> ## 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.

# Introduction

> Use the Stophy REST API: one base URL, bearer key authentication, a JSON body for every endpoint, and one response envelope for every call.

<Note>
  **For AI agents:** use [llms.txt](https://docs.stophy.dev/llms.txt) for a full index of these docs.
</Note>

Every Stophy endpoint uses the same base URL and bearer key. Data endpoints take a JSON body and return a consistent response.

## Features

<CardGroup cols={3}>
  <Card title="Search and AI answers" icon="magnifying-glass" color="f5d90a" href="/sources/web">Google results, news, images, papers and trends, and Google AI Mode answers.</Card>
  <Card title="Video" icon="video" color="f5d90a" href="/sources/video">YouTube, TikTok and Instagram videos, transcripts and comments.</Card>
  <Card title="Social" icon="users" color="f5d90a" href="/sources/social">Posts, profiles and comments from Reddit, Instagram, LinkedIn and Pinterest.</Card>
  <Card title="Places and travel" icon="map-location-dot" color="f5d90a" href="/sources/places-and-travel">Google Maps and Tripadvisor places and reviews, hotels and flights.</Card>
  <Card title="Jobs" icon="briefcase" color="f5d90a" href="/sources/jobs">Job listings from Google Jobs, LinkedIn, Indeed and Upwork.</Card>
  <Card title="Shopping" icon="cart-shopping" color="f5d90a" href="/sources/shopping">Amazon, Google Shopping and TikTok Shop products and prices.</Card>
  <Card title="Apps" icon="mobile-screen" color="f5d90a" href="/sources/apps">App Store and Google Play apps, reviews and charts.</Card>
  <Card title="Real estate" icon="house" color="f5d90a" href="/sources/real-estate">Homes for sale, for rent and sold from Zillow.</Card>
  <Card title="Ads" icon="bullhorn" color="f5d90a" href="/sources/ads">Ad libraries from Meta, Google, TikTok, LinkedIn, Microsoft and Pinterest.</Card>
</CardGroup>

See every endpoint in the sidebar, grouped the same way.

## Base URL

```text theme={null}
https://api.stophy.dev
```

Every endpoint is a `POST` with a JSON object body. The path is `/v1/` plus the endpoint id with dots as slashes: `google.search` is `/v1/google/search`, and `youtube.transcript` is `/v1/youtube/transcript`. Unknown input fields return `400`.

## Authentication

Create a key in the [dashboard](https://stophy.dev/signup). Send it with every request:

```text theme={null}
Authorization: Bearer <key>
```

<CodeGroup>
  ```bash cURL icon="terminal" theme={null}
  curl -X POST https://api.stophy.dev/v1/reddit/search \
    -H "Authorization: Bearer $STOPHY_API_KEY" \
    -H "content-type: application/json" \
    -d '{"query":"bun runtime"}'
  ```

  ```ts TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
  const response = await fetch("https://api.stophy.dev/v1/reddit/search", {
    method: "POST",
    headers: {
      authorization: "Bearer " + process.env.STOPHY_API_KEY,
      "content-type": "application/json",
    },
    body: JSON.stringify({ query: "bun runtime" }),
  });
  ```

  ```python Python icon="python" theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.stophy.dev/v1/reddit/search",
      headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
      json={"query": "bun runtime"},
      timeout=30,
  )
  ```
</CodeGroup>

An invalid or missing key returns `401` with code `unauthorized`.

## Responses

A successful call returns exactly `success`, `data`, `creditsUsed`, and `requestId`:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [{ "title": "Bun", "url": "https://bun.com/", "position": 1 }]
  },
  "creditsUsed": 1,
  "requestId": "7db121ac-d8e6-479a-b17c-59e3fe5fabd8"
}
```

`data` is a single object. A list is returned in `data.results`, with `data.cursor` when another page exists. Fields are not nested by owner: a value that belongs to a related resource carries that resource in its name, such as `videoId`, `videoUrl`, `channelName` and `placeId`. Empty values are omitted.

A failed call returns an error status and `{ "success": false, "error": { ... } }`. See [Errors](/api-reference/errors).

## One call, one page, one price

Each call returns one page. Most calls cost 1 credit and some cost 2. Five long lists cost 1 credit per 10 results. Instagram and TikTok transcripts cost more when the audio has to be transcribed. See [Credits and billing](/billing).

Some endpoints take `page`: send `page: 2`, then `3`, until `data.results` is empty. Others take `cursor`: send back the `cursor` from the response. The rest return everything in one call. See [Page through results](/guides/paging).

Request parameters are top-level fields of the JSON body. The body is the only input, and the response format is fixed.

## Send a link or an id

To point at one thing, a request names it the way the response does. Send its link or its id, never both: `videoUrl` or `videoId`, `placeUrl` or `placeId`, `userUrl` or `username`, `postUrl` or `postId` (Instagram: `postCode`), and so on. Each endpoint's reference lists the pair. Sending both, or neither, returns a `400`.


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