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

# Papers

> Search research papers by title and abstract, read one by id, DOI or arXiv id, and find similar papers. Needs an API key.

Use these endpoints for scholarly papers. All three need an API key. To mix papers into a web search, use `"categories": ["research"]` instead. See [Options](https://docs.stophy.dev/search/options.md#sources).

```bash cURL 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"
  }'
```

`GET /v1/search/research/papers` takes the same fields as query parameters.

```json theme={null}
{
  "success": true,
  "results": [
    {
      "paperId": "W4411630045",
      "primaryId": "doi:10.18653/v1/2024.eacl-demo.16",
      "title": "RAGAs: Automated Evaluation of Retrieval Augmented Generation",
      "year": 2024,
      "citedByCount": 537,
      "openAccessUrl": "https://aclanthology.org/2024.eacl-demo.16.pdf"
    }
  ],
  "costUsd": 0.001
}
```

`paperId` names the paper. `primaryId` is its best outside id: `arxiv:<id>`, else `doi:<DOI>`, else `openalex:<id>`. `ids` lists every known id. `year`, `venue` and `openAccessUrl` appear when known. `abstract` is an empty string when none exists.

| Field | Default | Effect |
| - | - | - |
| `query` | required | What to search for. |
| `k` | 40 | How many papers, 1 to 500. Not `limit`. |
| `authors` | none | Keep papers with an author whose name contains this text. |
| `from`, `to` | none | Keep papers from this year on, or up to this year, as `YYYY-MM-DD`. Only the year counts. `from` after `to` returns `400`. |
| `sort` | `relevance` | `relevance`, or `date_desc` for newest year first. |

`categories` returns `400`: the index has no categories.

## Read one paper

`GET /v1/search/research/papers/{id}` takes a `paperId`, `doi:<DOI>`, `arxiv:<id>` or `openalex:<id>`. A paper that is not found returns `404 notFound`. Add `query` to get the passage that matches it, and `k` (1 to 50, only with `query`). The index holds titles and abstracts, so the passage is the abstract and `note` says so. The answer has `paper`, and `passages` with the text and score. Without `query`, it has only `paper`.

## Find similar papers

`GET /v1/search/research/papers/{id}/similar?intent=evaluating+retrieval+augmented+generation&k=5` ranks papers by your `intent` and the title of the paper. Citations do not count. The paper you start from is left out of `results`, and `poolSize` is how many papers came back.

| Field | Default | Effect |
| - | - | - |
| `intent` | required | What the papers should be about. |
| `k` | 40 | How many papers, 1 to 500. |
| `anchor` | none | Another paper id to find papers like. Repeat for each. |
| `mode` | `similar` | Only `similar` works. `citers` and `references` return `400`: the index holds no citations. |

Walk through a literature search in [Research papers](https://docs.stophy.dev/recipes/research-papers.md). See [Pricing](https://docs.stophy.dev/account/pricing.md).


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