API Reference

OpenSkill REST API overview

Base URL

All API requests are made to:

https://openskill.dev/api

Authentication

Most API endpoints require authentication. Pass your access token in theAuthorization header:

Authorization: Bearer <access_token>

See the Authentication page for details on obtaining tokens via the device auth flow.

Rate Limiting

API requests are rate-limited to prevent abuse. Current limits:

EndpointLimitWindow
Search60 requestsper minute
Publish10 requestsper minute
Download120 requestsper minute
Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in all responses.

Error Responses

Errors follow a consistent JSON format:

Error response
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill not found"
  }
}
StatusDescription
400Bad request — invalid parameters
401Unauthorized — missing or invalid token
404Not found
429Rate limited

Endpoints Overview

MethodPathDescription
POST/api/auth/device/codeRequest device code
POST/api/auth/device/tokenExchange code for token
POST/api/auth/refreshRefresh access token
POST/api/auth/revokeRevoke refresh token
GET/api/skillsSearch skills
GET/api/skills/discoverDiscover skills from Git sources
GET/api/skills/[slug]Get skill details
POST/api/skills/publish/initInitialize publish (get upload URL)
POST/api/skills/publish/completeComplete publish after upload
GET/api/skills/[slug]/downloadDownload skill content
GET/api/skills/[slug]/versionsList skill versions
POST/api/skills/auditRun security audit
POST/api/telemetryReport telemetry events
CodexAuthentication