Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/org-quicko/skillset/llms.txt

Use this file to discover all available pages before exploring further.

The Skillset REST API is a JSON over HTTP interface that backs the web interface, CLI, and MCP server. Every endpoint lives under <PUBLIC_URL>/api, where PUBLIC_URL is the value you set in your Registry’s environment. This page explains the conventions that apply to every route: how to authenticate, what a paginated list looks like, and how errors are shaped.

​
Base URL

All endpoints are relative to your Registry’s origin: 
<PUBLIC_URL>/api
For a local Docker Compose install, PUBLIC_URL defaults to http://localhost:3000, so the base URL is: 
http://localhost:3000/api

​
Authentication

Catalog reads require no authentication. Any anonymous HTTP client can call:
  • GET /api/resources — browse the catalog
  • GET /api/resources/stats — hero counts
  • GET /api/resources/:kind/by-name/:name — fetch a Resource by name
  • GET /api/resources/:id — fetch a Resource by id
  • GET /api/resources/:id/installs/trend — install trend
  • GET /api/resources/:id/files — list Artifact files
  • GET /api/resources/:id/files/:path — read one Artifact file
  • GET /api/resources/:id/artifact — download the zip
  • GET /api/tags — list Tags
  • GET /api/auth/providers — list enabled Identity Providers

​
Role requirements

Every authenticated endpoint checks the caller’s role before executing:
RoleCan do
ReaderBrowse and install — catalog reads need no auth at all
WriterPublish, import, and manage own Tokens and Connections
AdminEverything a Writer can do, plus manage Users, Tags, Integrations, and Submissions
SuperadminFirst user; permanent Admin whose account cannot be altered
A user whose generated password has not yet been changed is blocked from all endpoints except GET /api/users/me and PUT /api/users/me/password. Both of those endpoints work regardless of must_change_password.

​
Request format

All request bodies must be JSON. Include the content-type header on every request that carries a body: 
Content-Type: application/json

​
Pagination

List endpoints that return many rows accept a page query parameter and respond with a pagination envelope. Some endpoints also accept page_size to control the number of results per page; others use a fixed page size. See each endpoint’s documentation for the exact parameters accepted.
FieldTypeDescription
itemsarrayThe records for this page
pageintegerThe current page (1-based)
page_sizeintegerRecords per page
totalintegerTotal matching records across all pages
Example: 
GET /api/resources?page=2&page_size=20

{
  "items": [...],
  "page": 2,
  "page_size": 20,
  "total": 83
}

​
Error format

Every error response uses the same JSON envelope: 
{
  "error": {
    "code": "<error_code>",
    "message": "<human-readable message>",
    "field": "<field name>"
  }
}
The field key is only present when the error is attributable to a specific request field (for example, a validation failure on email).

​
Common error codes

CodeStatusWhen it occurs
unauthenticated401No valid session or Token was presented
forbidden403The caller’s role is too low for this action
password_change_required403Generated password must be replaced before continuing
validation_failed400A request field failed validation
not_found404The requested resource does not exist
ambiguous_name409A bare name matched Resources in more than one Namespace
artifact_missing404The Resource exists but its Artifact was never uploaded
artifact_too_large413The stored Artifact exceeds the allowed size
email_taken409A User with that email already exists
superadmin_protected409The Superadmin’s account cannot be changed or removed
integration_in_use409An Integration cannot be deleted while Connections reference it
integration_not_configured409No Integration exists for the requested Git Provider
not_connected409The writer has no Connection for the requested provider
tag_name_conflict409A Tag with that name already exists
already_published409A Submission’s target (kind, namespace, name) is already in the Registry
source_required400A Submission must include a source repository URL
request_rejected4xxThe request was rejected by the framework (e.g. unsupported method or malformed body)
internal_error500An unexpected server-side failure

​
Rate limiting

Requests are rate-limited per client IP using a fixed window. The default limit is 600 requests per 60 seconds. Two endpoint groups have tighter per-path limits:
Path prefixLimit
/api/resources300 requests per 60 seconds
/api/imports60 requests per 60 seconds
When a load balancer or proxy sits in front of the Registry, set TRUSTED_PROXY_IPS in your environment to the proxy’s address so the real client IP is read from X-Forwarded-For instead of the socket. Leaving it empty behind a proxy collapses all traffic into one shared rate-limit bucket. When a limit is exceeded, the API responds with 429 rate_limited and a retry-after header indicating how many seconds to wait before retrying.

​
Endpoint groups

Resources

Publish, browse, download, and delete Resources. The core catalog API.

Tags

Browse the Tag catalog and rename Tags (admin).

Users

Manage accounts, roles, passwords, and personal Tokens.

Auth

Identity Provider list and the Better Auth session endpoints.

Imports

Read Skills from Git repositories through configured Integrations.

Integrations

Register and manage Git Provider app credentials (admin).

Connections

Grant the Registry personal access to your Git repositories.

Submissions

Submit community-sourced Resources and approve or reject them (admin).

Build docs developers (and LLMs) love

Get started for freeTalk to us