API Reference

The Skills Registry exposes a RESTful API for managing skills, versions, teams, and user accounts programmatically.

Base URL#

All API endpoints are relative to the base URL of your registry host. All request and response bodies are JSON unless otherwise noted.

https://csreg.nexus/api/v1

Example request using curl:

curl -s https://csreg.nexus/api/v1/skills \
  -H "Authorization: Bearer sk_abc123" \
  -H "Content-Type: application/json"

Authentication#

The API supports two authentication methods depending on the client.

Bearer Token (CLI)#

Pass an API token in the Authorization header. Tokens are created at /settings/tokens in the web UI or via the tokens API.

Header

Authorization: Bearer <token>

OAuth Session (Web)#

Cookie-based authentication via NextAuth. This is used automatically when browsing the web UI and requires no additional configuration.

Token Scopes#

API tokens are assigned a hierarchical scope that determines which operations they can perform. Higher scopes include all permissions from lower scopes.

Scope	Level	Permissions
`read`	0	Pull skills, browse, search
`write`	1	Push versions, create skills, manage channels. Includes read.
`admin`	2	Team management, yank versions, delete skills. Includes write + read.

Info

Higher scopes include all lower scope permissions. A token with admin scope can perform any operation that write or read tokens can.

Pagination#

List endpoints use cursor-based pagination. Pass a cursor query parameter to fetch the next page, and an optional limit to control page size. The default limit is 20 and the maximum is 100.

GET /api/v1/skills?cursor=<uuid>&limit=<n>

Paginated responses include a cursor field set to the ID of the last item. If cursor is present, more pages may be available.

Paginated Response

{
  "data": [...],
  "cursor": "uuid-of-last-item"
}

Errors#

Error responses follow the RFC 7807 Problem Details format. Every error includes a machine-readable type URI, a human-readable title, the HTTP status code, a detail message, and the request instance path.

Error Response

{
  "type": "https://csreg.nexus/errors/version-conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Version 1.2.0 of @backend/code-reviewer already exists.",
  "instance": "/api/v1/skills/backend/code-reviewer/versions"
}

The following error types may be returned by the API:

Status	Type	Description
400	`validation-error`	Request body or query parameters failed validation.
401	`authentication-required`	No valid authentication credentials provided.
403	`insufficient-permissions`	Token scope or role is insufficient for this operation.
404	`not-found`	The requested resource does not exist.
409	`version-conflict`	A resource with the same identifier already exists.
413	`archive-too-large`	The uploaded archive exceeds the maximum allowed size.
422	`manifest-invalid`	The skill manifest is malformed or missing required fields.
429	`rate-limit-exceeded`	Too many requests. Retry after the reset window.
500	`internal-error`	An unexpected server error occurred.

Rate Limiting#

Rate limiting is planned for a future release. The error type rate-limit-exceeded (429) is defined and will be used when rate limiting is enforced. Currently, there are no per-client rate limits.