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

# Sources

> Choose what a search returns: web pages, news, images, PDFs, research papers or YouTube videos. Each source and list is priced at $1 per 1,000 searches.

`sources` picks the kinds of results a [search](https://docs.stophy.dev/search/overview) returns, and `categories` adds PDFs, papers and videos. Each one comes back in its own list under `data`.

## Search several sources

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request asks for news, images, research papers and YouTube videos, two of each.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sqlite",
    "sources": ["news", "images"],
    "categories": ["research", "videos"],
    "limit": 2
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "sqlite",
    sources: ["news", "images"],
    categories: ["research", "videos"],
    limit: 2,
  }),
});
const { data } = await response.json();
console.log(Object.keys(data));
```

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

import requests

response = requests.post(
    "https://api.stophy.dev/v1/search",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "query": "sqlite",
        "sources": ["news", "images"],
        "categories": ["research", "videos"],
        "limit": 2,
    },
)
print(list(response.json()["data"]))
```

## Read the response

`data` has a `news`, an `images`, a `research` and a `videos` list. This real response is cut to one row of each, and the snippets are shortened.

```json theme={null}
{
  "success": true,
  "data": {
    "news": [
      {
        "title": "macOS 27 Siri Stores Conversations in SQLite Database, Raising Privacy Concerns",
        "url": "https://gbhackers.com/macos-27-siri-stores-conversations-in-sqlite-database",
        "snippet": "Apple’s new Siri app in macOS 27 retains conversations in a locally accessible SQLite database, …",
        "date": "2026-11-16T18:08:16.000Z",
        "position": 2
      }
    ],
    "images": [
      {
        "title": "Logo SQLite",
        "imageUrl": "https://sql.sh/wp-content/uploads/2014/04/sqlite-sgbd-500px.png",
        "imageWidth": 500,
        "imageHeight": 237,
        "url": "https://sql.sh/sgbd/sqlite",
        "position": 1
      }
    ],
    "research": [
      {
        "title": "SQLite",
        "url": "https://doi.org/10.14778/3554821.3554842",
        "doi": "10.14778/3554821.3554842",
        "snippet": "In the two decades following its initial release, SQLite has become the most widely deployed database engine in existence. …",
        "authors": ["Kevin P. Gaffney", "Martin Prammer", "Larry Brasfield"],
        "year": 2022,
        "venue": "Proceedings of the VLDB Endowment",
        "type": "article",
        "citedByCount": 86,
        "position": 1
      }
    ],
    "videos": [
      {
        "url": "https://www.youtube.com/watch?v=PGpL5hYpY1o",
        "title": "SQLite and its weird new fork “libSQL”",
        "channel": "Fireship",
        "channelUrl": "https://www.youtube.com/channel/UCsBjURrPoezykLs9EqgamOA",
        "publishedAt": "2024-01-01T00:00:00.000Z",
        "durationSeconds": 270,
        "views": 562257,
        "position": 2
      }
    ]
  },
  "id": "e976dc0c-46f8-4878-939e-e2bf44d4d80f",
  "costUsd": 0.004,
  "requestId": "e976dc0c-46f8-4878-939e-e2bf44d4d80f"
}
```

`costUsd` is $0.004: $0.001 for each of the four lists.

## Sources and categories

| Value | Goes in | What you get | Where in `data` | Price |
| - | - | - | - | - |
| `web` | `sources` | Web pages with `url`, `title`, `description`, and `date` and `category` when known. The default. | `web` | \$0.001 per 10 results |
| `news` | `sources` | News articles with `title`, `url`, `snippet`, `date` and `imageUrl`. Up to 50 per search. | `news` | \$0.001 per 10 results |
| `images` | `sources` | Images with `imageUrl`, `imageWidth`, `imageHeight` and the `url` of the page that holds them. | `images` | \$0.001 per 10 results |
| `pdf` | `categories` | Web results that are PDF files, each with `category` set to `pdf`. | `web` | \$0.001 per 10 results |
| `research` | `categories` | Scholarly papers ranked by relevance, then by citations. Each has `doi`, `authors`, `year`, `venue`, `type`, `citedByCount` and `openAccessUrl` when known, and a `snippet` from the abstract that matches the query. | `research` | \$0.001 per 10 results |
| `videos` | `categories` | YouTube videos in YouTube's order, with `channel`, `durationSeconds`, `views` and a watch `url`. A video whose captions Stophy holds also gets the `snippet` that matches the query and `startSeconds`, and its `url` carries `&t=`. | `videos` | \$0.001 per 10 results |

Each entry is a string or an object with a `type`, such as `"web"` or `{ "type": "web" }`. Send up to 5 sources. The web source is the only one that takes its own `tbs`, `location`, `country` and `lang`: `{ "type": "web", "tbs": "qdr:w", "country": "de" }`. See [Filters](https://docs.stophy.dev/search/filters.md).

With no `sources` you get web results. With only `research` or `videos` in `categories`, no web search runs. With `research` and `web`, the web results are limited to academic sites.

## Search PDFs

`categories: ["pdf"]` searches for PDF files. Any web result whose address ends in `.pdf` also gets `category: "pdf"`.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sqlite file format",
    "categories": ["pdf"],
    "limit": 2
  }'
```

This real response is cut to one of the two rows.

```json theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://www.tutorialspoint.com/sqlite/sqlite_tutorial.pdf",
        "title": "Preview SQLite Tutorial (PDF Version)",
        "description": "A complete SQLite database is stored in a single cross-platform disk file.",
        "position": 1,
        "category": "pdf"
      }
    ]
  },
  "id": "93541b34-9d2d-44bc-bc90-03e60b1a1e83",
  "costUsd": 0.001,
  "requestId": "93541b34-9d2d-44bc-bc90-03e60b1a1e83"
}
```

To read a PDF you found, add [page content](https://docs.stophy.dev/search/page-content.md) or send its address to [Scrape](https://docs.stophy.dev/scrape/pdfs-and-documents.md).

## Limits and errors

* A source that fails while others answer is left out, and `warning` names it, such as `news: …`. When every source fails, the call fails and costs nothing.
* An empty list costs nothing. `warning` says when a list came back empty, for example `research: no papers match these words. Try fewer or more general words.`
* With only `research` or `videos` and no `sources`, the fields that narrow web, news and image results return `400 invalidRequest`: `tbs`, `location`, `lang`, `includeDomains`, `excludeDomains`, `country` and `scrapeOptions`. The error names the field, such as `tbs narrows web, news and image results. Add them to sources or leave tbs out.` Add a source or leave the field out.
* An entry that is not `web`, `news` or `images` in `sources` returns `400 invalidRequest`. The error says `Send web, news or images, as a string or {"type":"web"}.`
* An entry that is not `pdf`, `research` or `videos` in `categories` returns `400 invalidRequest`. The error says `Send pdf, research or videos, as a string or {type}.`
* An `images` search needs words next to `imagesize:` or `larger:`, or it returns `400 invalidRequest`.

## Related

* [Filters](https://docs.stophy.dev/search/filters.md) narrows each source by site, time, place and language.
* [Page content](https://docs.stophy.dev/search/page-content.md) reads each web and news result.
* [Papers](https://docs.stophy.dev/search/papers.md) searches papers on their own and reads one by id.
* [Search overview](https://docs.stophy.dev/search/overview) lists every search field.


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