Resolve a Name
Turns a name as somebody actually writes it ("G19 gen 5 MOS", "AK-47", "H&K MP5") into a single catalog id, or says why it cannot.
- stringheaderrequired
Your API key.
Authorization: Bearer <key>is accepted in its place.
- stringrequired
The name to resolve, up to 200 characters.
- Max length
- 200
- Example
- object
What one query resolved to.
- string
The query this result answers, echoed back so a batch response can be matched to its request.
- string
One of
resolved(exactly one record),ambiguous(several equally good, none chosen) ornot_found. - string | null
The resolved catalog id. Null on
ambiguousandnot_found, since an ambiguous query is deliberately not decided for you. - string | null
How the resolution was made, or null when nothing resolved. Never
fuzzy: a suggestion is not a resolution. - number
Confidence in the resolution, 0 to 1. Derived from how much of the query a catalogued spelling accounted for and how strong that spelling is as evidence.
- string[]
The words of the query a catalogued spelling accounted for.
- string[]
The words it did not. Reported rather than guessed at: a variant we do not hold appears here instead of being silently dropped.
- object[]
Other records this query could mean, best first. On
ambiguousthese are the tied candidates and choosing between them is yours. - string
The catalog id of this candidate.
- string
The catalogued name of this candidate.
- string | null
The maker, or null where the record has none.
- string
How this candidate was matched. One of
slug,name,alternate,shorthand,base(the name with its maker removed),family(the model designation with its trailing descriptor removed, e.g.M4fromM4 Carbine) orfuzzy. - string | null
The catalogued spelling that matched, or null for a fuzzy suggestion.
- number
Confidence in this candidate, 0 to 1. Always 0 for a fuzzy suggestion, which is offered rather than scored.
- 400
VALIDATION_ERRORValidation error - 401
UNAUTHORIZEDAPI key required - 403
FORBIDDENValid key, not permitted - 429
RATE_LIMITEDRate limit exceeded - 500
INTERNAL_ERRORUnexpected server error
Requires an API key with Builder tier or higher.
Call this before anything else when you are starting from text rather than from an id. Every other endpoint takes a catalog id; this is the only one that takes a name as somebody wrote it.
It is not search. /v1/firearms/search ranks a page of records about a query and has no notion of certainty. This answers which record a query is, and tells you when it cannot.
status: "ambiguous" is an answer, not a failure. "Glock 19" is three generations, so firearmId is null and all three come back in alternatives for you to choose between. Treating an ambiguous result as a resolution is how an agent ends up quoting the wrong barrel length.
Words the resolver could not place come back in unresolvedTokens rather than being dropped. A variant we do not hold appears there, which is more useful than being handed the base model as though it were the answer.
A fuzzy candidate is a suggestion offered when nothing matched at all. It always scores 0 and never appears as a resolution.
A query that matches nothing is a 200 with status: "not_found", not a 404. The request was answerable; the answer is that we hold no such record.
- Minimum tier
- Builder+
- Monthly quota
- 25,000/mo
- Rate limit
- 60/min
- Daily cap
- 2,000
Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.
This read answers conditional requests. Keep the ETag from a response and send it back as If-None-Match: an unchanged record returns 304 Not Modified with no body, which counts toward your per-minute rate limit but not your daily allowance.