> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterskills.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> The HTTP API the masterskills CLI talks to — device-token auth, JSON everywhere.

The registry exposes a versioned HTTP API. The open-source CLI is its reference consumer; anything the CLI does, you can do directly.

```text theme={"dark"}
Base URL:   https://masterskills.dev/api/v1
Self-host:  <your-host>/api/v1
```

## Authentication

All endpoints authenticate with a **device token** unless noted otherwise:

```text theme={"dark"}
Authorization: Bearer <device_token>
```

Tokens are lifetime, per-device, and issued by the [device authorization flow](/api/device-flow). The server stores only a sha256 hash of each token. A `401` means the token is invalid or the device was revoked — obtain a new one via `masterskills login`.

A few endpoints (device approval, organization creation) are **panel-session** endpoints — they require a signed-in browser session at masterskills.dev, not a device token. They are marked where they appear.

## Conventions

* Request and response bodies are JSON.

* Errors use one envelope, with a proper HTTP status:

  ```json theme={"dark"}
  { "error": { "code": "device_limit", "message": "Free plan allows 1 device per user" } }
  ```

* Skills and kits are addressed as `@org/slug`; the `organizations.slug` is the namespace, stored without the `@`. Reads span **all** organizations the token's user belongs to; a pending (unapproved) membership grants no access anywhere.

## Endpoints

| Area                            | Endpoints                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Device flow](/api/device-flow) | `POST /device/code` · `POST /device/token` · `POST /device/approve`                                        |
| [Identity](/api/me)             | `GET /me`                                                                                                  |
| [Skills](/api/skills)           | `GET /skills` · `GET /skills/:org/:slug` · `GET …/versions/:number/download` · `DELETE /skills/:org/:slug` |
| [Sync](/api/sync)               | `POST /sync`                                                                                               |
| [Publishing](/api/publish)      | `POST /publish/prepare` · `POST /publish/:draftId/complete`                                                |
| [Kits](/api/kits)               | `GET /kits` · `POST /kits` · `GET /kits/:org/:slug` · `PATCH /kits/:org/:slug` · `DELETE /kits/:org/:slug` |