API Reference

REST API for managing organizations, skills, members, and tokens.

Base URL: https://app.skillreg.dev/api/v1

Authentication: Bearer token in the Authorization header.

Authorization: Bearer sk_your_token_here

Rate limits: 120 requests/min for API routes, 30 requests/min for search.

Authentication

GET/auth/whoami

Get the authenticated user and organization info.

Auth: Bearer token

Response

{
  "user": { "id": "...", "email": "...", "name": "..." },
  "org": { "id": "...", "slug": "acme", "name": "Acme Corp" }
}

POST/auth/cli/initiate

Start device authorization flow for CLI login.

Auth: None

Response

{
  "deviceCode": "abc-123",
  "userCode": "ABCD-1234",
  "verificationUrl": "https://app.skillreg.dev/auth/device",
  "expiresAt": "2026-01-01T00:10:00Z"
}

GET/auth/cli/poll?device_code={code}

Poll for CLI authentication completion.

Auth: None

Response

{ "status": "completed", "token": "sk_..." }

Skills

GET/orgs/{orgSlug}/skills

List all skills in an organization.

Auth: Bearer tokenScope: read

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)
search	string	Filter by name
tag	string	Filter by tag
sort	string	Sort: updated, name, downloads

Response

{
  "data": [{ "name": "code-reviewer", "description": "...", "latestVersion": "1.2.0" }],
  "pagination": { "page": 1, "limit": 20, "total": 42 }
}

GET/orgs/{orgSlug}/skills/{name}

Get skill details with latest version metadata.

Auth: Bearer tokenScope: read

PATCH/orgs/{orgSlug}/skills/{name}

Update skill metadata or deprecate a skill.

Auth: Bearer tokenScope: write

{ "description": "Updated description", "isDeprecated": true }

DELETE/orgs/{orgSlug}/skills/{name}

Delete a skill and all its versions.

Auth: Bearer tokenScope: admin

Versions

POST/orgs/{orgSlug}/skills/{name}/versions

Publish a new version. Send as multipart/form-data with the tarball.

Auth: Bearer tokenScope: write

Parameter	Type	Description
version	string	Semver version (required)
tarball	file	.tgz package (max 50MB)

Response

{ "version": "1.2.0", "sha256": "a3f8c2...", "size": 12345 }

GET/orgs/{orgSlug}/skills/{name}/versions

List all versions for a skill.

Auth: Bearer tokenScope: read

GET/orgs/{orgSlug}/skills/{name}/versions/{version}/download

Download the tarball for a specific version.

Auth: Bearer tokenScope: read

Collaboration

Collaboration MVP works on SKILL.md only. Contributors submit proposals, reviewers compose one candidate, then publish a normal official skill version from the web UI.

POST/orgs/{orgSlug}/skills/{name}/proposals

Create a proposal from local SKILL.md content.

Auth: Bearer tokenScope: write

{
  "title": "Clarify retries",
  "intent": "Explain retry behavior",
  "baseVersion": "1.4.0",
  "skillMdContent": "---\nname: sync\nversion: 1.4.0\n---\n# Sync\n..."
}

GET/orgs/{orgSlug}/skills/{name}/proposals

List proposals for a skill.

Auth: Bearer tokenScope: read

GET/orgs/{orgSlug}/skills/{name}/proposals/{proposalId}

Get one proposal for a skill.

Auth: Bearer tokenScope: read

GET/orgs/{orgSlug}/proposals/{proposalId}

Resolve a proposal by ID inside one organization.

Auth: Bearer tokenScope: read

GET/orgs/{orgSlug}/skills/{name}/candidate

Fetch or initialize the active candidate for reviewer workflows.

Auth: Bearer tokenScope: admin

PUT/orgs/{orgSlug}/skills/{name}/candidate

Select proposal IDs into the active candidate.

Auth: Bearer tokenScope: admin

{ "proposalIds": ["proposal-a", "proposal-b"] }

POST/orgs/{orgSlug}/skills/{name}/candidate/publish

Publish the active candidate as one official version.

Auth: Bearer tokenScope: admin

{ "bump": "patch", "changelog": "Clarify retries and examples" }

Registry (npm-like)

PUT/registry/{orgSlug}/{skillName}

Publish a skill version via the registry protocol.

Auth: Bearer tokenScope: write

GET/registry/{orgSlug}/{skillName}

Get skill metadata via the registry protocol.

Auth: Bearer tokenScope: read

Members

GET/orgs/{orgSlug}/members

List all members and pending invitations.

Auth: Bearer tokenScope: read

POST/orgs/{orgSlug}/members

Invite a member by email.

Auth: Bearer tokenScope: admin

{ "email": "user@example.com", "role": "member" }

PATCH/orgs/{orgSlug}/members/{userId}

Change a member's role.

Auth: Bearer tokenScope: admin

{ "role": "admin" }

DELETE/orgs/{orgSlug}/members/{userId}

Remove a member from the organization.

Auth: Bearer tokenScope: admin

Tokens

GET/orgs/{orgSlug}/tokens

List all API tokens for the organization.

Auth: Bearer tokenScope: admin

POST/orgs/{orgSlug}/tokens

Create a new API token.

Auth: Bearer tokenScope: admin

{ "name": "CI/CD Token", "scopes": ["read", "write"] }

Response

{ "token": "sk_...", "id": "...", "name": "CI/CD Token" }

DELETE/orgs/{orgSlug}/tokens/{tokenId}

Revoke an API token.

Auth: Bearer tokenScope: admin

Search

GET/search?q={query}&org={orgSlug}

Full-text search across public skills. No authentication required. Rate limited to 30 req/min.

Auth: None

Parameter	Type	Description
q	string	Search query (required)
org	string	Filter by organization (optional)
limit	number	Max results (default: 20)

RBAC Permissions

Action	Member	Admin	Owner
Read skills	Y	Y	Y
Download skills	Y	Y	Y
Publish skills	—	Y	Y
Delete skills	—	Y	Y
Manage members	—	Y	Y
Manage tokens	—	Y	Y
Org settings	—	—	Y
Delete org	—	—	Y

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill not found"
  }
}

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource already exists
VALIDATION_ERROR	422	Invalid request body
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error