Docs: GunSpec SDK

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

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

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 longest Retry-After a daily refusal sends. The value sent is the seconds left until the next midnight UTC, when the counters return to zero, so it is never more than this.
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

client.docs.listGuides()

Every guide the documentation renders, with the headings each is divided into: what is documented, and the ids and anchors to read it by.

listGuides(): Promise<APIResponse<DocsGuides>>

GET/v1/docs/guides

Explorer+

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

application/json

object
The response payload.
integer
How many guides there are.
object[]
Every guide, in the order the documentation lists them.
string
The guide's id, passed to the read endpoint.
string
The page's title.
string
The page a reader would open.
string
The opening prose: what the page is about.
integer
The whole page in Markdown, so a caller can tell what reading it costs.
object[]
Every heading on the page, in order.

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

Not yet in the Python SDK.

client.docs.searchGuides()

The sections of the guides that answer a question, best first. The entry point: search, then read the one section you need rather than a whole page. A question the guides do not cover returns no results rather than the nearest paragraph.

searchGuides(params: SearchDocsGuidesParams): Promise<APIResponse<DocsGuideSearch>>

GET/v1/docs/guides/search

Explorer+

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

stringrequired
The question, in the words it would be asked in.
Max length
200
Example
integerdefault8
How many sections to return.
Range
1 – 25
Example

application/json

object
The response payload.
string
The question as it was asked.
integer
How many sections matched, of which results carries the best.
object[]
The matching sections, best first.
string
The guide the section is on.
string
That guide's title.
string
The section's anchor.
string
The heading.
string
The heading with the ones above it.
string
The page, opened at that heading.
string
The opening of the section, so a caller can judge it without reading it.

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

Not yet in the Python SDK.

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.searchGuides({ q: 'how do I handle a 429' });6console.log(data);

1{2  "success": true,3  "data": {4    "query": "how do I handle a 429",5    "total": 34,6    "results": [7      {8        "guideId": "rate-limits",9        "guideTitle": "Rate Limits & Plans",10        "anchor": "rate-limits-retry",11        "title": "What to do when you are limited",12        "trail": "What to do when you are limited",13        "url": "https://docs.gunspec.io/en/rate-limits#rate-limits-retry",14        "snippet": "A 429 carries Retry-After in seconds."15      }16    ]17  }18}

Auth RequiredExplorer+

client.docs.getGuide()

One guide as Markdown: the whole page, or with anchor only that heading.

getGuide(id: string, params?: GetDocsGuideParams): Promise<APIResponse<DocsGuide>>

GET/v1/docs/guides/{id}

Explorer+

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

stringrequired
The guide's id, as the list endpoint gives it.
Accepts
a lowercase slug: letters, digits and hyphens
Example

string
Return only the section this heading anchor names. Omitted, the whole page comes back.
Max length
120
Example

application/json

object
The response payload.
string
The guide's id.
string
The page's title.
string
The page, opened at the section when one was named.
string
The opening prose. Sent with a whole page only.
string
The whole page as Markdown. Sent when no anchor was given.
object[]
The page's headings, or the named section - one anchor can hold several headings where a page deep-links only the outer one.
string
The heading's anchor.
string
The heading.
string
The heading with the ones above it.
string
The section's prose. Sent when an anchor was given.

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

Not yet in the Python SDK.

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.getGuide('caching');6console.log(data);

1{2  "success": true,3  "data": {4    "id": "caching",5    "title": "Caching and refreshing",6    "url": "https://docs.gunspec.io/en/caching#caching-policy",7    "summary": "You are encouraged to keep a local copy of the catalog.",8    "markdown": "## How long you may keep it\n\nEvery lifetime below…",9    "sections": [10      {11        "anchor": "caching-policy",12        "title": "How long you may keep it",13        "trail": "How long you may keep it",14        "markdown": "Every lifetime below is the value the API sends…"15      }16    ]17  }18}

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

AuthorizationExplorer+

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationExplorer+

Path Parameters

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits