# Papers

Look up scholarly metadata, full text where licensing allows, and citation graph edges.

## When to use

- You have a DOI, title, or paper ID and want metadata
- You need references or citing works for a known paper
- You are enriching your own dataset

## When not to use

- You have a question rather than an identifier → searches
- You need a formatted bibliography entry → citations

## Endpoints

| Method | Path | Scope | Credits | Description |
|---|---|---|---|---|
| GET | `/v1/papers/{id}` | `papers:read` | 0 | Retrieve by `pap_` ID or DOI |
| GET | `/v1/papers` | `papers:read` | 0 | Lookup by `doi`, `title`, or `query` |
| GET | `/v1/papers/{id}/full-text` | `papers:read` | 0 | Sectioned full text |
| GET | `/v1/papers/{id}/references` | `papers:read` | 0 | Outgoing references |
| GET | `/v1/papers/{id}/citations` | `papers:read` | 0 | Incoming citations |

## The paper object

```json
{
  "object": "paper",
  "id": "pap_3kf9wq2m8x",
  "doi": "10.48550/arXiv.1706.03762",
  "title": "Attention Is All You Need",
  "abstract": "The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder. The best performing models also connect the encoder and decoder through an attention mechanism. We propose a new simple network architecture, the Transformer, based solely on attention mechanisms, dispensing with recurrence and convolutions entirely. Experiments on two machine translation tasks show these models to be superior in quality while being more parallelizable and requiring significantly less time to train.",
  "tldr": "Replaces recurrence and convolution with self-attention alone, training faster and scoring higher on translation.",
  "publication_date": "2017-06-12",
  "publication_type": "preprint",
  "language": "en",
  "open_access": {
    "is_open_access": true,
    "status": "green",
    "licence": "arXiv perpetual non-exclusive",
    "pdf_url": "https://arxiv.org/pdf/1706.03762"
  },
  "is_retracted": false,
  "citation_count": 142387,
  "url": "https://scispace.com/papers/pap_3kf9wq2m8x",
  "venue": {
    "name": "arXiv",
    "type": "preprint_server",
    "issn": null,
    "publisher": "Cornell University"
  },
  "volume": null,
  "issue": null,
  "pages": null,
  "authors": [
    {
      "name": "Ashish Vaswani",
      "orcid": null,
      "affiliation": {
        "name": "Google Brain",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Noam Shazeer",
      "orcid": null,
      "affiliation": {
        "name": "Google Brain",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Niki Parmar",
      "orcid": null,
      "affiliation": {
        "name": "Google Research",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Jakob Uszkoreit",
      "orcid": null,
      "affiliation": {
        "name": "Google Research",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Llion Jones",
      "orcid": null,
      "affiliation": {
        "name": "Google Research",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Aidan N. Gomez",
      "orcid": null,
      "affiliation": {
        "name": "University of Toronto",
        "country": "CA",
        "ror": "https://ror.org/03dbr7087"
      }
    },
    {
      "name": "Łukasz Kaiser",
      "orcid": null,
      "affiliation": {
        "name": "Google Brain",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    },
    {
      "name": "Illia Polosukhin",
      "orcid": null,
      "affiliation": {
        "name": "Google Research",
        "country": "US",
        "ror": "https://ror.org/00njsd438"
      }
    }
  ],
  "subjects": [
    "Computer Science",
    "Machine Learning",
    "Computation and Language"
  ]
}
```

## Fields

| Field | Type | Description |
|---|---|---|
| `id` | string | `pap_`-prefixed identifier. Stable; use it rather than the DOI as your key |
| `doi` | string | Canonical DOI. `null` for works that have none |
| `title` | string | As published |
| `abstract` | string | Publisher abstract. `null` where licensing forbids redistribution |
| `tldr` | string | One-sentence machine summary. Not a substitute for the abstract |
| `publication_date` | string | `YYYY-MM-DD`; day precision may be approximate for older works |
| `publication_type` | enum | `journal_article`, `preprint`, `conference_paper`, `book_chapter`, `thesis`, `report` |
| `language` | string | BCP-47 |
| `open_access.is_open_access` | boolean | Whether a legally readable full text exists |
| `open_access.status` | enum | `gold`, `green`, `hybrid`, `bronze`, `closed` |
| `open_access.licence` | string | e.g. `CC-BY-4.0`. Governs what you may store — see content-licensing |
| `open_access.pdf_url` | string | Publisher-hosted PDF. `null` when closed |
| `is_retracted` | boolean | **Check this before citing.** Retraction propagates within 7 days |
| `citation_count` | integer | Inbound citations. Refreshed weekly |
| `venue` | object | `name`, `type`, `issn`, `publisher` |
| `volume` / `issue` / `pages` | string | Bibliographic locators. `null` for preprints |
| `authors[]` | array | Ordered as published. `affiliation` may be `null` |
| `authors[].affiliation.ror` | string | ROR identifier, for disambiguating institutions |
| `subjects[]` | array | Field-of-study labels, broadest first |

> [!warning] Retracted work stays in the corpus
> It is returned with `is_retracted: true` rather than removed, so citations to it can still resolve.
> Filter it out of anything user-facing.

> [!danger] Redistribution limits apply
> Full text and abstracts are licensed content. What you may store, cache, or display is governed by
> content-licensing.

## Full text availability

Full text is returned only where we are licensed to serve it. Check `open_access.is_open_access`
before requesting it.

| Case | Response |
|---|---|
| Open access, PDF held | `200` with sections |
| Licensed via publisher agreement | `200` with sections; `licence` field states the restriction |
| Not licensed to you | `403 full_text_not_licensed` |
| No PDF anywhere | `404 full_text_unavailable` |

Sections are returned as an ordered array of `{ heading, level, text }`. Reference lists, figures, and
tables are separate arrays so you do not have to parse them out of the body.

All paper reads are free (credit), so check availability before you build a fallback.

## Errors

| Status | `code` | When |
|---|---|---|
| 404 | `paper_not_found` | unknown ID or DOI |
| 403 | `full_text_not_licensed` | full text exists but is not available to you |

## Related

paper · citations · content-licensing · migrate-from-openalex