# Collections

Read a publicly shared, user-curated collection of firearms by its share ID. No API key required. Collections are created and edited from the GunSpec dashboard; only collections set to `public` are resolvable here.

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

## Get Shared Collection

`GET /v1/collections/{shareId}`

Auth: Optional API key  
Tier: Explorer+

Returns a user collection that has been shared publicly, together with the firearms in it. The 10-character share id is the only credential; unshared collections are not reachable here.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shareId` | string | yes | 10-character public share id |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The response payload. |
| `data.id` | string | Internal id of the collection. Not a credential; the share id is. |
| `data.name` | string | Display name, as the maker writes it. |
| `data.description` | string \| null | Prose summary of the record, where one has been written. |
| `data.shareId` | string | The 10-character public share id, echoing the path parameter. |
| `data.itemCount` | integer | How many firearms the collection holds. |
| `data.createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |
| `data.items` | FirearmListItem[] | The rows this response carries. |
| `data.items[].id` | string | URL-safe slug identifying the firearm, e.g. `glock-g17-gen5`. Stable: it is what a mirror keys on. |
| `data.items[].name` | string | Display name, as the maker writes it. |
| `data.items[].manufacturerId` | string | Slug of the manufacturer that makes it. Resolve against `/v1/manufacturers/{id}`. |
| `data.items[].categoryId` | string | Slug of the category it belongs to. Resolve against `/v1/categories`. |
| `data.items[].yearIntroduced` | integer \| null | Year it entered production or service. Null where the date is disputed or unknown. |
| `data.items[].status` | FirearmStatus \| null | Production status, one of `in_production`, `discontinued`, `out_of_production`, `in_service`, `limited_production`, `prototype`. Discontinued records are kept deliberately: a rifle built in 2004 wears parts nobody sells today. |
| `data.items[].countryOfOrigin` | string \| null | ISO 3166-1 alpha-2 code of where it was designed, e.g. `AT`. |
| `data.items[].actionType` | string \| null | How the action cycles: `short_recoil`, `gas_operated`, `blowback`, `bolt_action` and so on. An open vocabulary: the values in use are published on the schema as `x-gunspec-vocabulary`, and `GET /v1/firearms/action-types` is the live list. |
| `data.items[].weightEmptyG` | number \| null | Unloaded weight in grams, without magazine. |
| `data.items[].barrelLengthMm` | number \| null | Barrel length in millimetres, measured from the breech face. |
| `data.items[].images` | InlineMediaItem[] | Every image this firearm has, silhouette first. Empty when none are on file. |
| `data.items[].createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |

```json
{
  "success": true,
  "data": {
    "id": "col_01H8",
    "name": "Service pistols",
    "description": "Standard-issue sidearms",
    "shareId": "a1b2c3d4e5",
    "itemCount": 12,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "items": [
      {
        "id": "glock-g17-gen5",
        "name": "Glock 17 Gen5",
        "manufacturerId": "glock",
        "categoryId": "pistol",
        "yearIntroduced": 2017,
        "status": "in_production",
        "countryOfOrigin": "AT",
        "actionType": "short_recoil",
        "weightEmptyG": 625,
        "barrelLengthMm": 114,
        "images": [
          {
            "id": 2572,
            "url": "https://api.gunspec.io/v1/firearms/ak-47/images/2572",
            "kind": "silhouette",
            "alt": "AK-47 right profile",
            "width": 1536,
            "height": 1024
          }
        ],
        "createdAt": "2026-09-06 23:55:07",
        "svgLineArtUrl": "https://api.gunspec.io/v1/firearms/glock-g17-gen5/media/silhouette",
        "model3dUrl": null,
        "favoriteCount": 0,
        "updatedAt": "2026-09-10 06:42:19",
        "version": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"
      }
    ]
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 404 | `NOT_FOUND` | Resource not found |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- No API key required.
- Only collections with `visibility: public` are resolvable. Private collections return 404.
- Items are returned in curator order (`sort_order` ascending).
- Collections are created and edited from the GunSpec dashboard, not via the API.

### Example

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