---
title: "Get available filter values"
method: GET
path: "/v1/firearms/filter-options"
tags: ["Firearm Discovery"]
---

# Get available filter values

`GET /v1/firearms/filter-options`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/firearms/filter-options`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns the distinct values available for each filterable field, for building filter UIs without hardcoding the options. Categories, manufacturers and calibers no firearm uses are omitted.

Available on every plan. Requires an API key; Explorer keys receive a reduced field set.

## Headers

- `If-None-Match` string

## Response `200`

Get available filter values

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The distinct filter values currently present in the catalog.
    - `manufacturers` object[]: Manufacturers with at least one firearm.
      - `id` string: Slug of the manufacturer, and the value to send as `manufacturer`.
      - `name` string: Display name, as the maker writes it.
      - `countryCode` string, nullable: ISO 3166-1 alpha-2 code of where they are based, for grouping the list by country.
    - `categories` object[]: Categories with at least one firearm.
      - `slug` string: Slug of the category, and the value to send as `category`. Keyed `slug` here rather than `id`, unlike the other lists.
      - `name` string: Display name, as the maker writes it.
    - `calibers` object[]: Cartridges chambered by at least one firearm.
      - `id` string: Slug of the cartridge, and the value to send as `caliber`.
      - `name` string: Display name, as the maker writes it.
    - `actionTypes` object[]: Operating actions present in the catalog.
      - `id` string: The action type as stored, and the value to send as `action_type`.
      - `name` string: Display name, as the maker writes it.
    - `features` object[]: JSON array of notable features, as a string. The same vocabulary `/v1/firearms/by-feature` filters on.
      - `id` string: The feature as stored, and the value to send as `feature` to /v1/firearms/by-feature.
      - `name` string: Display name, as the maker writes it.

## Other responses

- `304`: Your copy is current. No body is sent, and this response does not count toward the daily request allowance.
- `400`: Validation error
- `401`: Missing or invalid API key
- `403`: The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work.
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

[API](https://skmtc.dev/gunspec/apis/gunspec-io-api.md) · [All operations](https://skmtc.dev/gunspec/apis/gunspec-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gunspec/apis/gunspec-io-api/revisions/f2e974d8b05c?raw)