# Papers

Technical reports GunSpec publishes on the catalogue: each with its named authors, what review it has had, the methods its figures are computed by and the API requests that reproduce them. Both reads need an API key, on every plan including the free one, and return only published papers. The Papers tab explains what a paper is, how one is made and how to reproduce and cite it.

Source: https://docs.gunspec.io/en/api/papers

## List Research Papers

`GET /v1/papers`

Auth: API key required  
Tier: Explorer+

Returns the research papers GunSpec has published, newest first: technical reports built on the catalogue and the published methods.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number, from 1 to 10,000 |
| `per_page` | integer | no | Items per page (max 100) |
| `topic` | string | no | Filter by topic |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | object[] | A research paper as the public reads serve it. |
| `data[].id` | string | Paper id. |
| `data[].slug` | string | URL segment of the paper on the research site. |
| `data[].title` | string | Paper title. |
| `data[].abstract` | string \| null | The abstract, as plain text. |
| `data[].body` | string \| null | The paper in markdown. A `gunspec-chart` fence names a chart by the catalogue data it draws. |
| `data[].keyFindings` | string[] | The findings, one sentence each, for a reader with a minute. |
| `data[].reportType` | string | What kind of document it is. |
| `data[].reviewStatus` | string | What the research has been through. Publication on the research site is not a review; `peer_reviewed` means a venue accepted it. |
| `data[].venue` | string \| null | Where it was submitted or published, when it was. |
| `data[].doi` | string \| null | Its DOI as registered, never a URL. |
| `data[].authors` | object[] | Named authors, in order. |
| `data[].authors[].name` | string | Author name. |
| `data[].authors[].affiliation` | string \| null | Author affiliation. |
| `data[].topic` | string \| null | What the paper is about, as a slug. |
| `data[].dataVersion` | string \| null | The catalogue data the figures were computed on. |
| `data[].methods` | string[] | The documentation Methods pages its figures are computed by, by slug. |
| `data[].apiCalls` | string[] | API calls that reproduce its figures. |
| `data[].heroImage` | string \| null | The hero picture, as a path on the research site. |
| `data[].heroAlt` | string \| null | What the hero shows, as alt text. |
| `data[].status` | string | Always `published` on a public read. |
| `data[].publishedAt` | string \| null | When it went public. |
| `data[].createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |
| `data[].updatedAt` | string | When a field we serve last changed. |
| `pagination.page` | number | Current page number |
| `pagination.per_page` | number | Items per page |
| `pagination.total` | number | Total matching records (Builder and above) |

```json
{
  "success": true,
  "data": [
    {
      "id": "5f0c1e8a-2d3b-4c6e-9a1f-7b8c9d0e1f2a",
      "slug": "rifle-mass-and-the-energy-cost-of-a-foot-march",
      "title": "Rifle mass and the energy cost of a foot march",
      "abstract": null,
      "body": null,
      "keyFindings": [
        "string"
      ],
      "reportType": "technical_report",
      "reviewStatus": "not_reviewed",
      "venue": null,
      "doi": null,
      "authors": [
        {
          "name": "GunSpec Research",
          "affiliation": "GunSpec.io"
        }
      ],
      "topic": "load-carriage",
      "dataVersion": null,
      "methods": [
        "load-carriage"
      ],
      "apiCalls": [
        "/v1/firearms/load-carriage?ids=hk416,fn-scar-l"
      ],
      "heroImage": null,
      "heroAlt": null,
      "status": "published",
      "publishedAt": "2026-09-30T00:00:00.000Z",
      "createdAt": "2026-09-29T00:00:00.000Z",
      "updatedAt": "2026-09-30T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "per_page": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Needs an API key, on every plan including the free one. Only published papers are returned, newest first.
- Filter with `topic` to list the papers on one subject.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/papers' \
  --header 'X-API-Key: your_key'
```

## Get Research Paper

`GET /v1/papers/{slug}`

Auth: API key required  
Tier: Explorer+

Returns one published research paper, including its full body, its authors, its review status and the API calls that reproduce its figures.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | Paper slug |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The paper, wrapped as the blog read wraps a post. |
| `data.paper` | object | A research paper as the public reads serve it. |
| `data.paper.id` | string | Paper id. |
| `data.paper.slug` | string | URL segment of the paper on the research site. |
| `data.paper.title` | string | Paper title. |
| `data.paper.abstract` | string \| null | The abstract, as plain text. |
| `data.paper.body` | string \| null | The paper in markdown. A `gunspec-chart` fence names a chart by the catalogue data it draws. |
| `data.paper.keyFindings` | string[] | The findings, one sentence each, for a reader with a minute. |
| `data.paper.reportType` | string | What kind of document it is. |
| `data.paper.reviewStatus` | string | What the research has been through. Publication on the research site is not a review; `peer_reviewed` means a venue accepted it. |
| `data.paper.venue` | string \| null | Where it was submitted or published, when it was. |
| `data.paper.doi` | string \| null | Its DOI as registered, never a URL. |
| `data.paper.authors` | object[] | Named authors, in order. |
| `data.paper.topic` | string \| null | What the paper is about, as a slug. |

```json
{
  "success": true,
  "data": {
    "paper": {
      "id": "5f0c1e8a-2d3b-4c6e-9a1f-7b8c9d0e1f2a",
      "slug": "rifle-mass-and-the-energy-cost-of-a-foot-march",
      "title": "Rifle mass and the energy cost of a foot march",
      "abstract": null,
      "body": null,
      "keyFindings": [
        "string"
      ],
      "reportType": "technical_report",
      "reviewStatus": "not_reviewed",
      "venue": null,
      "doi": null,
      "authors": [
        {
          "name": "GunSpec Research",
          "affiliation": "GunSpec.io"
        }
      ],
      "topic": "load-carriage",
      "dataVersion": null,
      "methods": [
        "load-carriage"
      ],
      "apiCalls": [
        "/v1/firearms/load-carriage?ids=hk416,fn-scar-l"
      ],
      "heroImage": null,
      "heroAlt": null,
      "status": "published",
      "publishedAt": "2026-09-30T00:00:00.000Z",
      "createdAt": "2026-09-29T00:00:00.000Z",
      "updatedAt": "2026-09-30T00:00:00.000Z"
    }
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 404 | `NOT_FOUND` | Resource not found |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Needs an API key, on every plan including the free one. A slug that is unknown, a draft or a paper scheduled for later answers 404.
- `apiCalls` lists the requests that reproduce the paper's figures. Send them with your own key; some need a paid plan.
- `reviewStatus` says what review the paper has had. Publishing a paper is not a review.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/papers/rifle-mass-and-the-energy-cost-of-a-foot-march' \
  --header 'X-API-Key: your_key'
```