# Rokha API Documentation

> The OS for the agentic world — find a capability and it actually runs, with traces to prove it.

## Authentication

Rokha uses wallet-based authentication with JWT tokens.

### Auth Flow

1. `POST /api/wallets/challenge` with `{"wallet_address": "...", "wallet_type": "phantom"}`
2. Sign the returned message with your wallet
3. `POST /api/wallets/verify` with `{"challenge_id": "...", "signature": "...", "wallet_address": "..."}`
4. Response includes JWT token (valid 24h)
5. Include `Authorization: Bearer <token>` in all protected requests
6. `POST /api/auth/refresh` to renew before expiry

## Public Endpoints (No Auth)

### Registry

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/marketplace/registry` | List all synced tools and MCP servers |
| GET | `/api/marketplace/registry/stats` | Provider counts and sync status |
| GET | `/api/marketplace/registry/sync` | Latest sync status per provider |
| GET | `/api/marketplace/registry/:provider/:id` | Single listing detail (JSON) |
| GET | `/api/marketplace/registry/:provider/:id/md` | Single listing (Markdown) |

#### Registry Query Parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | string | — | Filter by provider (`clawhub`, `smithery`, `smithery_skills`, `mcp_official`, `glama`, `skills_sh`, `docker_mcp`, `anthropic_skills`) |
| `listing_type` | string | — | Filter by type (`skill`, `server`, `harness`, `rig`) |
| `search` | string | — | Search title, description, author |
| `tag` | string | — | Filter by tag |
| `sort` | string | `downloads` | Sort: `downloads`, `stars`, `updated`, `name` |
| `execution_class` | string | — | Filter by execution class (`prompt`, `scripted`, `mcp`) |
| `limit` | int | 50 | Results per page (max 200) |
| `offset` | int | 0 | Pagination offset |

#### Registry Response Shape

```json
{
  "items": [
    {
      "name": "skill-name",
      "description": "...",
      "version": "1.0.0",
      "author": "author-name",
      "homepage": "https://...",
      "downloads": 12345,
      "stars": 67,
      "tags": ["mcp", "search"],
      "source": "clawhub",
      "listing_type": "skill",
      "external_id": "skill-slug",
      "provider_id": "clawhub",
      "external_updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total_count": 150,
  "limit": 50,
  "offset": 0
}
```

### Discovery

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/discovery/tools` | Live MCP tool discovery |
| GET | `/api/discovery/agents` | Running agent discovery |
| GET | `/api/discovery/protocols` | Protocol capabilities |
| GET | `/api/discovery/all` | Combined discovery |
| GET | `/api/discovery/hot` | Trending tools |

### Marketplace

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/marketplace/listings` | Browse marketplace listings |
| GET | `/api/marketplace/listings/:id` | Get listing detail |
| POST | `/api/marketplace/search` | Search marketplace |
| GET | `/api/marketplace/featured` | Featured listings |
| GET | `/api/marketplace/stats` | Marketplace statistics |

### Markdown Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/llms.txt` | AI/LLM discovery index |
| GET | `/api/docs.md` | This document |
| GET | `/api/marketplace/skills.md` | Full skills catalog as markdown |

`/api/marketplace/skills.md` supports the same query params as `/api/marketplace/registry`.

### MCP Protocol

| Method | Path | Description |
|--------|------|-------------|
| GET | `/mcp/tools` | List available MCP tools |
| GET | `/mcp/resources` | List MCP resources |
| GET | `/mcp/prompts` | List MCP prompts |
| POST | `/mcp/jsonrpc` | Execute MCP tools (anonymous discovery/authoring set needs no auth; wallet-scoped tools ride a JWT) |

Protocol version: `2025-11-25`

## Protected Endpoints (JWT Required)

### Agents

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/agents/rokha-agent/chat` | Chat with Rokha AI |
| GET | `/api/agents/rokha-agent/status` | Rokha status |
| GET | `/api/agents/rokha-agent/available-models` | List available models |
| POST | `/api/agents/rokha-agent/set-model` | Switch model |

### Tasks

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/agents/tasks` | Create task |
| GET | `/api/agents/tasks` | List tasks |
| GET | `/api/agents/tasks/:id` | Get task |
| PUT | `/api/agents/tasks/:id` | Update task |
| POST | `/api/agents/tasks/:id/start` | Start task |

## Sensitive Endpoints (JWT + Wallet Signature)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/users/lookup` | Lookup user by wallet |
| GET | `/api/users/:id` | Get user profile |
| GET/POST | `/api/harnesses/*` | Memory/context CRUD |

Requires additional headers: `x-wallet-signature`, `x-challenge-id`

## Rate Limits

| Tier | LLM Requests/Day | Scopes |
|------|-------------------|--------|
| Free | 100 | read, write |
| Dev | Unlimited | read, write, admin |

---
*Served by [Rokha Registry](https://rokha.ai)*