Docs

Resource class for the documentation endpoints. Instantiated internally by the GunSpec client and exposed as client.docs.

Auth RequiredExplorer+

client.docs.getOperations()

Look up what the reference documents for an operation: parameters, the plan it needs, caching, every failure with its error.reason values, and the languages a sample is printed in.

getOperations(params: GetDocsOperationsParams): Promise<APIResponse<DocsOperations>>

GET/v1/docs/operations

Explorer+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringrequired
The operation's path: a documented template, a concrete path or a full URL. A path that names no operation is matched as a prefix.
Max length
300
Example
string
Narrow to one HTTP method. Omitted returns every method the path answers.
Accepts
Example

application/json

object
The response payload.
string
exact when the path named an operation, prefix when it did not and these are the operations under it (at most 25).
string
The version of this document the reference was rendered from.
object[]
The matching operations.
string
HTTP method.
string
The documented path template.
string
The operation's title in the reference.
string
What the operation does, as the reference states it.
string
The lowest plan that may call it: public, account (a key attached to a user account), explorer, builder, studio or enterprise.
string
Whether a key is required, optional or not used (none).
boolean
Whether it answers 304 Not Modified to an If-None-Match carrying the ETag it sent.
string
The operation's page in the reference.
object[]
Path, query and header parameters, as the reference lists them.
object | null
The request body, or null for an operation that takes none.
object
What success looks like.
object[]
Every failure the operation documents.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Explorer+
Monthly quota: 200/mo
Rate limit: 10/min
Daily cap: 50

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.docs.getOperations({ path: '/v1/firearms/{id}', method: 'GET' });6console.log(data.operations[0]?.tier, data.operations[0]?.parameters.map((p) => p.name));

1{2  "success": true,3  "data": {4    "matched": "exact",5    "specVersion": "1.0.0",6    "operations": [7      {8        "method": "GET",9        "path": "/v1/firearms/{id}",10        "title": "Get Firearm",11        "description": "Returns the full specification of one firearm.",12        "tier": "builder",13        "auth": "required",14        "cacheable": true,15        "docsUrl": "https://docs.gunspec.io/en/api/firearms/get",16        "parameters": [17          {18            "name": "id",19            "in": "path",20            "type": "string",21            "required": true,22            "description": "Firearm slug",23            "accepts": [24              "string"25            ],26            "default": "20",27            "minimum": 1,28            "maximum": 10029          }30        ],31        "requestBody": {32          "contentType": "application/json",33          "example": "{\"name\": \"Glock 19\"}"34        },35        "success": {36          "status": 200,37          "contentType": "application/json"38        },39        "errors": [40          {41            "status": 404,42            "message": "Not found",43            "code": "NOT_FOUND",44            "reasons": [45              "RESOURCE_NOT_FOUND"46            ]47          }48        ],49        "notes": [50          "string"51        ],52        "sampleLanguages": [53          "python"54        ],55        "sdk": [56          {57            "typescript": "client.firearms.get(id)",58            "python": "client.firearms.get(id: str)"59          }60        ]61      }62    ]63  }64}

Auth RequiredExplorer+

client.docs.getSample()

Get the sample the reference prints for an operation in one language, exactly as printed, with the result of the last run that checked it.

getSample(params: GetDocsSampleParams): Promise<APIResponse<DocsSamples>>

GET/v1/docs/samples

Explorer+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringrequired
The operation's path: a documented template, a concrete path or a full URL.
Max length
300
Example
string
The HTTP method. Needed only when the path answers more than one.
Accepts
Example
stringrequired
curl, javascript (TypeScript with fetch), python (requests), unity, unreal, godot, or sdk-typescript / sdk-python for the SDKs.
Accepts
Example

application/json

object
The response payload.
string
HTTP method of the operation.
string
Its documented path template.
string
The lowest plan that may call it.
string
The operation's page in the reference.
string
The language asked for.
string | null
How to fill in the key placeholder, or null for an operation that takes no key.
object[]
One sample, or one per SDK method for an operation more than one method calls.
string
What the sample is: the tab name, or the SDK call.
string
The sample, exactly as the reference prints it.
object | null
The last run that checked this sample, or null when none has.
string | null
Anything to know before using it, such as why it is not executed, or null.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Explorer+
Monthly quota: 200/mo
Rate limit: 10/min
Daily cap: 50

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.docs.getSample({ path: '/v1/firearms', method: 'GET', language: 'curl' });6console.log(data.samples[0]?.code, data.samples[0]?.verification?.status);

1{2  "success": true,3  "data": {4    "method": "GET",5    "path": "/v1/firearms",6    "tier": "explorer",7    "docsUrl": "https://docs.gunspec.io/en/api/firearms/list",8    "language": "python",9    "keyNote": "Replace your_key with a GunSpec API key, sent as the X-API-Key header.",10    "samples": [11      {12        "label": "Python (requests)",13        "code": "import requests",14        "verification": {15          "status": "passed",16          "checkKind": "executed",17          "ranAt": "2026-09-17T08:50:16.655Z"18        },19        "note": null20      }21    ]22  }23}

Auth RequiredExplorer+

client.docs.getLimits()

What each plan allows: requests per minute, day and month, MCP calls per day, paging depth, and how long to wait after a 429.

getLimits(): Promise<APIResponse<DocsLimits>>

GET/v1/docs/limits

Explorer+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

application/json

object
The response payload.
object[]
Every plan, cheapest first.
string
Plan id.
string
Plan name.
integer
Monthly price in US cents.
integer
Requests allowed per minute, per key.
integer
Requests allowed per day, per key.
integer
Requests included per month.
integer
Calls through the hosted MCP server allowed per day, inside the daily request allowance.
integer | null
The deepest page a list may be read to, or null for no limit.
boolean
Whether paginated responses include the total count.
object
Limits on a caller that sends no key.
integer
Requests allowed per day to the endpoints that need no key.
integer | null
The deepest page a list may be read to without a key.
object
How fast a list may be paged through before PAGINATION_BURST is returned.
integer
Pages that may be read in quick succession.
integer
The window those pages are counted over.
object
How long to wait after a 429.
integer
The Retry-After sent with a per-minute refusal.
integer
The Retry-After sent when the daily allowance is spent.
string[]
The headers a key may be sent in.
string
The rate limits page in the docs.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Explorer+
Monthly quota: 200/mo
Rate limit: 10/min
Daily cap: 50

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.docs.getLimits();6for (const plan of data.plans) console.log(plan.name, plan.requestsPerMinute, plan.requestsPerDay);

1{2  "success": true,3  "data": {4    "plans": [5      {6        "tier": "builder",7        "name": "Builder",8        "priceUsdCentsPerMonth": 2900,9        "requestsPerMinute": 60,10        "requestsPerDay": 2000,11        "requestsPerMonth": 25000,12        "mcpCallsPerDay": 500,13        "maxPage": 25,14        "totalCountInLists": true15      }16    ],17    "withoutKey": {18      "requestsPerDay": 50,19      "maxPage": 520    },21    "paginationBurst": {22      "pages": 10,23      "windowSeconds": 9024    },25    "retryAfterSeconds": {26      "rateLimited": 60,27      "dailyCapReached": 360028    },29    "keyHeaders": [30      "X-API-Key: <key>"31    ],32    "docsUrl": "https://docs.gunspec.io/en/rate-limits"33  }34}

Docs

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Response200application/json

Errors

Rate limitsFull rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits