# arXiv Paper

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/arxiv/paper` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/arxiv-paper |

## Description

Fetch one arXiv paper by id or by an abs, pdf, or html URL.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/arxiv/paper' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### cond-mat/0011267

```json
{
  "doi": null,
  "url": "https://arxiv.org/abs/cond-mat/0011267v1",
  "title": "The electronic structure of cuprates from high energy spectroscopy",
  "authors": [
    {
      "name": "Mark S. Golden",
      "affiliation": null
    },
    {
      "name": "Christian Duerr",
      "affiliation": null
    },
    {
      "name": "Andreas Koitzsch",
      "affiliation": null
    },
    {
      "name": "Sibylle Legner",
      "affiliation": null
    },
    {
      "name": "Zhiwei Hu",
      "affiliation": null
    },
    {
      "name": "Sergey Borisenko",
      "affiliation": null
    },
    {
      "name": "Martin Knupfer",
      "affiliation": null
    },
    {
      "name": "Joerg Fink",
      "affiliation": null
    }
  ],
  "comment": "J. Electron Spec. Relat. Phenom.: special issue on electron correlation, in press",
  "pdf_url": "https://arxiv.org/pdf/cond-mat/0011267v1",
  "updated": "2000-11-15T16:19:15Z",
  "version": 1,
  "abstract": "We report studies of the electronic structure and elementary excitations of doped and undoped cuprate chains, ladders and planes. Using high energy spectroscopies such as x-ray absorption, core level photoemission and angle resolved photoemission spectroscopy, important information regarding the charge distribution and hole dynamics can be obtained. The comparison of the experimental data with suitable theoretical models sets constraints on the parameters entering into the model calculations, and offers insight into the important physical quantities governing the electronic structure of these materials. Recurring themes include the importance of the dimensionality of the Cu-O network (1D->2D) and the crucial role played by the spin-background in determining the dynamics of low-lying excitations in these strongly correlated systems.",
  "arxiv_id": "cond-mat/0011267",
  "published": "2000-11-15T16:19:15Z",
  "categories": [
    "cond-mat.supr-con",
    "cond-mat.str-el"
  ],
  "journal_ref": "J. Electron Spectr. Relat. Phenom. 117-118, 203 (2001)",
  "primary_category": "cond-mat.supr-con"
}
```

## Documentation

## Overview
Fetch one arXiv paper. `query` is an id such as `2201.00978` or `cond-mat/0011267`, with or without a version suffix (`2201.00978v1`), or an abstract, PDF, or HTML URL on arxiv.org. The response is one flat object, not a `results` list.

Take `arxiv_id` or `url` from search and pass it here.

## Quickstart
```
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/paper?query=2201.00978"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/paper?query=cond-mat/0011267"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/arxiv/paper?query=https%3A%2F%2Farxiv.org%2Fabs%2F2201.00978"
```

## Parameters
| Name | Detail |
|---|---|
| query | Required string. arXiv id or an abs, pdf, or html URL. Example: `2201.00978` or `https://arxiv.org/abs/cond-mat/0011267v1`. |

## Response fields
| Name | Detail |
|---|---|
| arxiv_id | String. Id without the version. |
| version | Integer or null. |
| title | String. |
| authors | Array of `{name, affiliation}`. |
| abstract | String or null. |
| primary_category | String or null. |
| categories | Array of strings. |
| published | String or null. UTC timestamp. |
| updated | String or null. UTC timestamp. |
| comment | String or null. |
| journal_ref | String or null. |
| doi | String or null. |
| pdf_url | String or null. |
| url | String. Abstract page, including the version when one was requested. |

## Pagination
This endpoint returns one paper. There is no `pagination` object.

## Use cases
- A reading list opens `cond-mat/0011267` from search and stores `authors`, `abstract`, and `pdf_url`.
- A reference manager accepts `https://arxiv.org/abs/2201.00978v1` and keeps `version` plus `categories`.
- A literature review reads `journal_ref` and `doi` after the preprint is published.

## Error codes
| Name | Detail |
|---|---|
| 400 | Missing `query`, a host other than arxiv.org, or a URL that is not an abs, pdf, or html path. |
| 404 | Unknown id. |
| 401 | Missing API key. |
| 500 | The arXiv request failed. |

## Related endpoints
- [arXiv Search](https://www.piloterr.com/library/arxiv-search)