# INSPIRE REST API

[INSPIRE](https://inspirehep.net) is a trusted community hub that helps researchers share and find accurate scholarly information in high energy physics. The REST API provides programmatic access to its content.

> Official documentation: [github.com/inspirehep/rest-api-doc](https://github.com/inspirehep/rest-api-doc)

## Base URL

```
https://inspirehep.net/api/
```

All website URLs have a corresponding API endpoint by prefixing the path with `/api/`. For example:

```
Website:  https://inspirehep.net/literature?sort=mostrecent&size=25&q=title api
API:      https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
```

## Record Types

| Type           | Description                    |
|----------------|--------------------------------|
| `literature`   | Papers, theses, reports        |
| `authors`      | Author records                 |
| `institutions` | Institutional affiliations     |
| `conferences`  | Conference records             |
| `seminars`     | Seminar/seminar records        |
| `journals`     | Journal records                |
| `jobs`         | Job postings                   |
| `experiments`  | Experiment records             |
| `data`         | Research data records          |

## Obtaining a Single Record

### By Internal ID (recid)

```
GET /api/{record-type}/{recid}
```

Example — Maldacena's AdS/CFT paper:
```
https://inspirehep.net/api/literature/451647
```

### By External Identifier

| Identifier Type | Example Value                  | Usage                        |
|-----------------|--------------------------------|------------------------------|
| `doi`           | `10.1103/PhysRevLett.19.1264`  | Lookup literature by DOI     |
| `arxiv`         | `1207.7214`, `hep-ph/0603175`  | Lookup literature by arXiv ID|
| `orcid`         | `0000-0003-3897-046X`          | Lookup author by ORCID iD    |

Example — Stephen Hawking's author record:
```
https://inspirehep.net/api/orcid/0000-0002-9079-593X
```

## Response Format (Single Record)

Default JSON response contains:

| Key        | Description                              |
|------------|------------------------------------------|
| `id`       | Identifier used to retrieve the record   |
| `created`  | Creation timestamp (UTC)                 |
| `updated`  | Last update timestamp (UTC)              |
| `links`    | Links to related resources and alt formats |
| `metadata` | Record metadata (conforms to JSON schema) |

Schema documentation: [inspire-schemas.readthedocs.io](https://inspire-schemas.readthedocs.io/en/latest/schemas/)

## Output Formats

For **literature** records only, use the `format` query parameter or content negotiation via the `Accept` header.

| Format        | MIME Type                                  | Description                     |
|---------------|--------------------------------------------|---------------------------------|
| `json`        | `application/json`                         | Default JSON (always available) |
| `json-expanded`| `application/vnd+inspire.record.expanded+json` | JSON with ROR/ORCID inlined |
| `bibtex`      | `application/x-bibtex`                     | BibTeX format                   |
| `latex-eu`    | `application/vnd+inspire.latex.eu+x-latex` | LaTeX (EU) format              |
| `latex-us`    | `application/vnd+inspire.latex.us+x-latex` | LaTeX (US) format              |
| `cv`          | `text/vnd+inspire.html+html`              | CV in HTML format               |

### Examples

BibTeX via query parameter:
```
https://inspirehep.net/api/literature/4328?format=bibtex
```

BibTeX via content negotiation:
```bash
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
```

## Searching

```
GET /api/{record-type}?{query-string}
```

### Query Parameters

| Parameter | Description                              |
|-----------|------------------------------------------|
| `q`       | Search query                             |
| `sort`    | Sort order                               |
| `size`    | Results per page (max 1000, default 10)  |
| `page`    | Page number (1-indexed)                  |
| `fields`  | Comma-separated list of metadata fields  |

### Search Query Syntax (`q`)

For **literature** records, use the [INSPIRE search syntax](https://inspirehep.net/help/knowledge-base/inspire-paper-search/) (compatible with SPIRES/old INSPIRE). Additionally, any metadata field can be searched using dot-notation:

```
q=abstracts.source:Springer
q=dois.value:*
```

For **other record types**, use [ElasticSearch query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/7.1/query-dsl-query-string-query.html):

```
q=accelerator.value:PS
q=ids.value:INSPIRE-00140145
```

### Citations vs. References

These two search operators look at the citation graph from opposite directions:

| Operator | Direction | Meaning | Example |
|----------|-----------|---------|---------|
| `citedby:recid:XXXX` | Outgoing | Papers that this record **cites** (what do I cite?) | `?q=citedby:recid:451647` |
| `refersto:recid:XXXX` | Incoming | Papers that **cite** this record (who cites me?) | `?q=refersto:recid:451647` |

Full URL examples:

```
# Papers in Maldacena's AdS/CFT bibliography (what it cites)
https://inspirehep.net/api/literature?q=citedby:recid:451647

# Papers citing Maldacena's AdS/CFT paper (who cites it)
https://inspirehep.net/api/literature?q=refersto:recid:451647
```

Both support all standard search modifiers (sorting, pagination, format export).

### Common Search Examples

```bash
# Papers by an author (SPIRES-style)
?q=a E.Witten.1

# Conference papers citing an author
?q=tc conference paper and refersto a E.Witten.1

# Papers cited at least 1000 times
?q=topcite 1000+

# Papers with a specific title word
?q=title:scattering

# Check if a field exists
?q=dois.value:*
```

### Sort Options

| Record Type   | Sort Value   | Description                           |
|---------------|--------------|---------------------------------------|
| `literature`  | `mostrecent` | Most recent first                     |
| `literature`  | `mostcited`  | Most cited first                      |
| `jobs`        | `mostrecent` | Most recently created first           |
| `jobs`        | `deadline`   | Earliest deadline first               |
| `conferences` | `dateasc`    | Earliest start date first             |
| `conferences` | `datedesc`   | Most recent start date first          |
| `seminars`    | `dateasc`    | Earliest start time first             |
| `seminars`    | `datedesc`   | Most recent start time first          |

Default behavior:
- No query (`q`) → sorted by most recent
- With query (`q`) → sorted by relevance

### Pagination

- Default: 10 results per page
- Max: 1000 results per page
- Technical limit: 10,000 total results per query
- Follow `links.next` in the response for the next page

Example — Get results 31–40:
```
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
```

### Search Response

```json
{
  "hits": {
    "total": 243,
    "hits": [
      {
        "id": "...",
        "created": "...",
        "updated": "...",
        "links": { ... },
        "metadata": { ... }
      }
    ]
  },
  "links": {
    "next": "https://inspirehep.net/api/literature?...&page=2"
  }
}
```

#### Extra Fields in Literature Search Results

| Field                              | Example      | Description                        |
|------------------------------------|--------------|------------------------------------|
| `earliest_date`                    | `2020-03-18` | Earliest date on the record        |
| `citation_count`                   | `243`        | Total citation count               |
| `citation_count_without_self_citations` | `213`   | Citations excluding self-citations |

### Metadata Filtering (`fields`)

Reduce response size by requesting only specific fields:

```
https://inspirehep.net/api/literature?fields=titles,authors.full_name&q=topcite 1000+
```

Get citation count for a single record:
```
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
```

Note: `fields` filtering only works in search endpoints, not single-record endpoints.

## Export All Citations (BibTeX)

To export BibTeX for all papers matching a search (e.g., all papers citing a given record):

```
https://inspirehep.net/api/literature?sort=mostrecent&size=1000&page=1&q=refersto:recid:XXXXXX&format=bibtex
```

If the result set exceeds 1,000 entries, paginate with `page=2`, `page=3`, etc.

## Export All References (BibTeX)

To export BibTeX for all papers referenced by a given record (i.e., its bibliography):

```
https://inspirehep.net/api/literature?sort=mostrecent&size=1000&page=1&q=citedby:recid:XXXXXX&format=bibtex
```

If the result set exceeds 1,000 entries, paginate with `page=2`, `page=3`, etc.

## Bibliography Generator

Generate a bibliography from a TeX file containing `\cite{...}` commands.

```bash
curl -XPOST -F "file=@/path/to/texfile.tex" \
  "https://inspirehep.net/api/bibliography-generator?format=bibtex"
```

Supported formats: `bibtex`, `latex_eu`, `latex_us`

## Rate Limiting

- **15 requests per 5 seconds** per IP address
- HTTP 429 status code when exceeded
- Blocked requests still count toward the quota
- Wait at least 5 seconds after receiving a 429

## Citation

If you use the API in scholarly work, cite:

```bibtex
@article{Moskovic:2021zjs,
    author = "Moskovic, Micha",
    title = "{The INSPIRE REST API}",
    url = "https://github.com/inspirehep/rest-api-doc",
    doi = "10.5281/zenodo.5788550",
    month = "12",
    year = "2021"
}
```