HTTP API reference

Machine-readable spec: airskills.ai/openapi.json — OpenAPI 3.1, fetch it directly to generate clients, recreate the server, or feed an LLM. The CLI is just one client of this contract; nothing stops you pointing it at your own implementation.

Authentication

All API routes require a Bearer token:

Authorization: Bearer <access-token>

The CLI gets a token by running airskills login, which opens a browser window for sign-in and stores the result in ~/.airskills/token. The CLI refreshes the token automatically.

If you are building a tool other than the CLI, two paths are supported:

• REST API access — use the CLI's stored token. Run airskills login, then read ~/.airskills/token (JSON with access_token and refresh_token fields). Refresh via POST /api/v1/auth/refresh with {"refresh_token": "..."}.
• MCP server access — use OAuth 2.1 with Dynamic Client Registration against https://airskills.ai/mcp. See the MCP getting-started guide for details. This is the recommended path for MCP clients like Claude Desktop, Cursor, etc.

There is no dashboard UI to copy an API key from — tokens are issued by airskills login or by the MCP OAuth flow.

Base URL

https://airskills.ai/api/v1

Skills

GET /skills

List all skills accessible to the authenticated user.

POST /skills

Create a new skill.

Body:

{
  "name": "my-skill",
  "content": "...",
  "description": "optional"
}

GET /skills/:id

Get a skill by ID.

PATCH /skills/:id

Update a skill's content or metadata.

Headers:

• X-Expected-Commit — the last known head_commit_id for conflict detection

DELETE /skills/:id

Soft-delete a skill.

GET /skills/:id/restore

Restore a soft-deleted skill.

PUT /skills/:id/archive

Archive (soft-delete) a skill and get back the current owner details.

GET /skills/:id/skillsets

List all skillsets that include this skill.

Skillsets

GET /skillsets

List all skillsets for the authenticated user's organization.

POST /skillsets

Create a new skillset.

GET /skillsets/:slug

Get a skillset and its member skills.

llms.txt

The llms.txt file at airskills.ai/llms.txt provides a machine-readable index of this API documentation for use with AI coding agents.