# HTTP API Reference

The API server provides a RESTful interface to SkillLane. Start it with `skilllane serve`.

**Base URL:** `http://localhost:3080` (default)

**Response format:** All responses are JSON with `{ok: boolean, data?: unknown, error?: string}`.

---

## Authentication

Some routes require authentication when `SKILLLANE_REQUIRE_AUTH=true` is set.

```
Authorization: Bearer <token>
```

Set the token with `SKILLLANE_API_AUTH_TOKEN=<token>`.

### Auth requirements by route

- **No auth:** `GET /health`, `GET /skills`, `GET /skills/search`, `GET /skills/:name`, `GET /registry`, `GET /registry/stats`, `GET /doctor`, `POST /demo`
- **Auth required:** `POST /init`, `POST /skills/create`, `POST /skills/validate`, `POST /skills/install`, `POST /skills/:name/run`, `POST /skills/:name/export`, `DELETE /skills/:name`, `POST /registry/rebuild`

---

## Routes

### Health

#### `GET /health`

Health check.

**Response:**

```json
{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "0.1.0"
  }
}
```

#### `GET /v1/skilllane/health`

Same as `/health`.

---

### Diagnostics

#### `GET /v1/skilllane/doctor`

Run system health checks.

**Response:**

```json
{
  "ok": true,
  "data": {
    "healthy": true,
    "checks": [
      {"name": "storage", "status": "ok", "message": "Storage initialized"},
      {"name": "registry", "status": "ok", "message": "3 skills installed"},
      {"name": "node", "status": "ok", "message": "Node.js v22.0.0"}
    ]
  }
}
```

---

### Initialize

#### `POST /v1/skilllane/init`

Initialize the SkillLane storage directory.

**Response:**

```json
{
  "ok": true,
  "data": {"initialized": true}
}
```

---

### Skills

#### `POST /v1/skilllane/skills/create`

Create a new skill.

**Request body:**

```json
{
  "name": "my-skill",
  "description": "A custom skill",
  "title": "My Skill",
  "category": "engineering",
  "tags": ["debugging"],
  "targets": ["codex", "opencode"],
  "template": "debugging",
  "outDir": "./skills"
}
```

**Response:**

```json
{
  "ok": true,
  "data": {
    "path": "./skills/my-skill",
    "metadata": {...},
    "skillMd": "...",
    "tools": [...],
    "status": "active"
  }
}
```

#### `POST /v1/skilllane/skills/validate`

Validate a skill directory.

**Request body:**

```json
{
  "path": "./my-skill",
  "strict": false
}
```

**Response:**

```json
{
  "ok": true,
  "data": {
    "valid": true,
    "score": 85,
    "errors": [],
    "warnings": ["metadata.tags is empty"],
    "checkedFiles": ["SKILL.md", "metadata.json", "tools.json", "examples.md", "eval.md"],
    "metadata": {...}
  }
}
```

#### `POST /v1/skilllane/skills/install`

Install a skill from a path.

**Request body:**

```json
{
  "source": "./my-skill",
  "builtin": false,
  "name": "custom-name",
  "force": false
}
```

**Response:**

```json
{
  "ok": true,
  "data": {
    "name": "my-skill",
    "version": "0.1.0",
    "title": "My Skill",
    "description": "...",
    "category": "engineering",
    "targets": ["codex", "opencode"],
    "tags": ["debugging"],
    "path": "/root/.skilllane/skills/my-skill",
    "installedAt": "2026-01-15T10:30:00.000Z",
    "builtin": false
  }
}
```

#### `GET /v1/skilllane/skills`

List installed skills.

**Query parameters:**

| Parameter | Description |
|-----------|-------------|
| `tag` | Filter by tag |
| `category` | Filter by category |

**Response:**

```json
{
  "ok": true,
  "data": [
    {
      "name": "systematic-debugging",
      "version": "0.1.0",
      "title": "Systematic Debugging",
      "category": "engineering",
      "tags": ["debugging"],
      "path": "/root/.skilllane/skills/systematic-debugging",
      "builtin": true
    }
  ]
}
```

#### `GET /v1/skilllane/skills/search`

Search skills.

**Query parameters:**

| Parameter | Description |
|-----------|-------------|
| `q` | Search query |

**Response:**

```json
{
  "ok": true,
  "data": [...]
}
```

#### `GET /v1/skilllane/skills/:name`

Get skill details.

**Response:**

```json
{
  "ok": true,
  "data": {
    "name": "systematic-debugging",
    "version": "0.1.0",
    "title": "Systematic Debugging",
    "description": "...",
    "category": "engineering",
    "tags": ["debugging"],
    "path": "/root/.skilllane/skills/systematic-debugging"
  }
}
```

#### `POST /v1/skilllane/skills/:name/run`

Run a skill.

**Request body:**

```json
{
  "task": "Debug a TypeError",
  "context": "Cannot read property of undefined",
  "target": "opencode",
  "outputMode": "markdown"
}
```

**Response:**

```json
{
  "ok": true,
  "data": {
    "skill": "systematic-debugging",
    "prompt": "## Role\n\nYou are executing...",
    "outputMode": "markdown",
    "target": "opencode",
    "tools": ["read_file", "grep", "run_command"]
  }
}
```

#### `POST /v1/skilllane/skills/:name/export`

Export a skill to a tarball.

**Request body:**

```json
{
  "outPath": "./backup.tar.gz"
}
```

**Response:**

```json
{
  "ok": true,
  "data": "./systematic-debugging.tar.gz"
}
```

#### `DELETE /v1/skilllane/skills/:name`

Remove an installed skill.

**Response:**

```json
{
  "ok": true,
  "data": {"removed": "my-skill"}
}
```

---

### Registry

#### `GET /v1/skilllane/registry`

Get registry info and stats.

**Response:**

```json
{
  "ok": true,
  "data": {
    "registry": "skilllane",
    "totalSkills": 3,
    "categories": {"engineering": 2, "marketing": 1},
    "tags": {"debugging": 1, "code-review": 1}
  }
}
```

#### `POST /v1/skilllane/registry/rebuild`

Rebuild registry from installed skills.

**Response:**

```json
{
  "ok": true,
  "data": {"rebuilt": true}
}
```

#### `GET /v1/skilllane/registry/stats`

Get registry statistics.

**Response:**

```json
{
  "ok": true,
  "data": {
    "totalSkills": 3,
    "categories": {"engineering": 2, "marketing": 1},
    "tags": {"debugging": 1}
  }
}
```

---

### Demo

#### `POST /v1/skilllane/demo`

Run the demo.

**Response:**

```json
{
  "ok": true,
  "data": {
    "success": true,
    "output": "SkillLane v0.1.0 Demo\nStorage: initialized\nRegistry: ready"
  }
}
```

---

## CORS

The server includes CORS headers for browser access:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

---

## Error Responses

All error responses follow this format:

```json
{
  "ok": false,
  "error": "Error message here"
}
```

Common HTTP status codes:

| Status | Description |
|--------|-------------|
| 400 | Bad request / invalid JSON |
| 401 | Authorization required |
| 403 | Invalid token |
| 404 | Route not found |
| 500 | Internal server error |