# REST API

Runtime skill discovery via HTTP

## REST API

Skills shouldn't require pre-installation. With the SkillKit REST API, any agent, framework, or tool can discover and retrieve skills on demand over HTTP.

## Start the server

```
skillkit serve
```

That's it. The API is now running at `http://localhost:3737`.

## Search for skills

```
curl "http://localhost:3737/search?q=react+performance"
```

```
{
  "skills": [
    {
      "name": "react-performance",
      "description": "React app performance optimization",
      "source": "anthropics/skills",
      "tags": ["react", "performance"],
      "score": 87
    }
  ],
  "total": 42,
  "query": "react performance",
  "limit": 20
}
```

Results are ranked by a multi-signal scoring system. The best matches come first.

### With filters

Use POST for advanced filtering:

```
curl -X POST http://localhost:3737/search \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "auth",\n    "filters": { "tags": ["security"], "category": "backend" }\n  }'
```

### Include full content

Add `include_content=true` to get the complete SKILL.md body:

```
curl "http://localhost:3737/search?q=pdf&include_content=true&limit=3"
```

## Get a specific skill

```
curl http://localhost:3737/skills/anthropics/skills/pdf-processing
```

The path follows the pattern `/skills/:owner/:repo/:skill-name`.

## Browse trending skills

```
curl http://localhost:3737/trending?limit=10
```

Returns the top skills ranked by relevance score across all sources.

## List categories

```
curl http://localhost:3737/categories
```

```
{
  "categories": [
    { "name": "react", "count": 156 },
    { "name": "typescript", "count": 134 },
    { "name": "testing", "count": 89 }
  ],
  "total": 89
}
```

## How ranking works

Every search result gets a score from 0 to 100, computed from four signals:

| Signal | Points | What it measures |
| --- | --- | --- |
| Content | 40 | Has a description and SKILL.md body |
| Query match | 30 | How well the name/description matches your search |
| Popularity | 15 | GitHub stars + install count (log-scaled) |
| References | 15 | Has example files, docs, or resources |

A skill with full content, an exact name match, high stars, and example files scores close to 100. A skill with just a name and no content scores around 10.

## Server options

```
skillkit serve --port 8080 --host localhost --cors "http://localhost:3000"
```

| Option | Default | What it does |
| --- | --- | --- |
| `--port` / `-p` | `3737` | Port to listen on |
| `--host` / `-H` | `0.0.0.0` | Host to bind to |
| `--cors` | `*` | Allowed CORS origin |
| `--cache-ttl` | `86400000` | Cache lifetime in ms (default 24h) |

## Rate limiting

60 requests per minute per IP. Response headers tell you where you stand:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Remaining` | Requests left in this window |
| `X-RateLimit-Reset` | When the window resets |

Exceed the limit and you'll get HTTP 429 with a `retryAfter` field.

## Caching

Search results are cached in memory using an LRU strategy. Same query, same results, no recomputation. Check cache performance:

```
curl http://localhost:3737/cache/stats
```

```
{
  "hits": 142,
  "misses": 38,
  "size": 45,
  "maxSize": 500,
  "hitRate": 0.789
}
```

## Health check

```
curl http://localhost:3737/health
```

```
{
  "status": "ok",
  "version": "1.19.2",
  "skillCount": 15062,
  "uptime": 3600
}
```

## Use it programmatically

```
import { createApp, startServer } from '@skillkit/api';

const { server, app, cache } = await startServer({
  port: 3737,
  skills: mySkillsArray,
});
```

Or get just the Hono app for testing:

```
const { app, cache } = createApp({
  skills: mySkillsArray,
  cacheTtlMs: 3_600_000,
});
```

## Interactive docs

The server includes built-in Swagger UI at `/docs` and an OpenAPI 3.1 spec at `/openapi.json`. Open `http://localhost:3737/docs` in your browser to try endpoints interactively.

The hosted version is available at [skillkit.sh/api](https://skillkit.sh/api) and [agenstskills.com/api](/content/api/index.html).

## All endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/search?q=...` | Search skills |
| POST | `/search` | Search with filters |
| GET | `/skills/:owner/:repo/:id` | Get specific skill |
| GET | `/trending?limit=20` | Trending skills |
| GET | `/categories` | Skill categories |
| GET | `/health` | Server health |
| GET | `/cache/stats` | Cache statistics |
| GET | `/docs` | Swagger UI |
| GET | `/openapi.json` | OpenAPI spec |