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

# Research papers

> Find recent papers on a topic, keep the ones with an open PDF, and read their first pages as Markdown with a source for every note.

Find papers by title and abstract, then read open PDFs for the notes you cite. Paper search needs `STOPHY_API_KEY`. See the [Quickstart](https://docs.stophy.dev/quickstart.md).

## 1. Search for papers

This request asks for up to 3 papers from 2024 on, newest first.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/search/research/papers \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "retrieval augmented generation", "k": 3, "from": "2024-01-01", "sort": "date_desc" }'
```

`results` holds papers with `paperId`, `primaryId` (the best outside ID), `title`, `abstract`, `authors`, `year`, `venue`, `citedByCount` and `openAccessUrl`. The index can return a paper with no abstract, so do not rely on it for claims. `openAccessUrl` may be a PDF or a landing page. Keep the papers whose link ends in `.pdf` or points at `arxiv.org/pdf`. See [Papers](https://docs.stophy.dev/search/papers.md) for options.

## 2. Read a paper

Scrape reads a direct PDF link as Markdown. This request reads the first 2 pages and cuts the text at 2,000 characters.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://aclanthology.org/2024.eacl-demo.16.pdf",
    "parsers": [{ "type": "pdf", "maxPages": 2 }],
    "maxChars": 2000
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "Proceedings of the 18th Conference of the European Chapter of the Association for Computational Linguistics\nSystem Demonstrations, pages 150–158\n…",
    "nextOffset": 1969,
    "warning": "The page text was cut short. Send offset 1969 to read on.",
    "metadata": { "contentType": "application/pdf", "numPages": 9, "totalPages": 9 }
  }
}
```

`totalPages` is the pages in the file. Send the same request with `"offset": 1969` to read on, a larger `maxPages` for more pages, and `pageMarkers: true` to see where each page starts. A PDF that comes back empty may need `"mode": "ocr"` in the PDF options. See [PDFs and documents](https://docs.stophy.dev/scrape/pdfs-and-documents.md).

## 3. Read every paper

Repeat step 2 for each result with a direct PDF link. Keep the paper's `primaryId` as `id`, with its title, year and Markdown as `text`. Hand each note to a model with the instruction to quote only from `text` and cite `id`. For a paper you hold as a file, [Parse](https://docs.stophy.dev/parse/overview) gives the same Markdown from an upload.

## Check it

* `results` matches your topic. If not, change the query, or add `authors`, `from` and `to`.
* Each note contains the paper's title. A PDF can open with publication details before it.
* Read on with `nextOffset` when the answer needs the methods or results.
* Every claim in your summary is a quote you can find in `text`. Check three.

See [Pricing](https://docs.stophy.dev/account/pricing.md) for search and PDF read costs. To read one paper by id, see [Papers](https://docs.stophy.dev/search/papers.md).


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