Skip to content

api-reference.md

Latest commit

 

History

History
202 lines (143 loc) · 3.32 KB

api-reference.md

File metadata and controls

202 lines (143 loc) · 3.32 KB
Raw

API Reference

All API routes are in apps/web/app/api/. They use Next.js App Router conventions with NextRequest and NextResponse.

Error Response Format

All errors follow this format:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Status Codes

Code Meaning
200 Success
201 Created
400 Validation error
401 Missing or invalid API key
404 Resource not found
409 Conflict (slug collision, version conflict)
429 Rate limited (OpenRouter)
500 Internal server error
502 Upstream error (OpenRouter)

Skills

List Skills

GET /api/skills

Query parameters:

  • search -- Filter by name, description, or tags
  • status -- Filter by draft, ready, or deployed
  • page -- Page number (default: 1)
  • limit -- Items per page (default: 12)
  • sort -- Sort field: updated_at, name, created_at
  • order -- Sort direction: asc, desc

Create Skill

POST /api/skills
Content-Type: application/json

{
  "name": "PR Reviewer",
  "description": "Reviews pull requests",
  "trigger": "When user asks to review a PR",
  "tags": ["review", "pr"],
  "content": "## Instructions\n..."
}

Get Skill

GET /api/skills/[id]

Update Skill

PUT /api/skills/[id]
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  ...
}

Delete Skill

DELETE /api/skills/[id]

Cascades to skill_files, skill_versions, and test_runs.

AI Chat

Stream Chat Response

POST /api/chat
Content-Type: application/json

{
  "messages": [{ "role": "user", "content": "Create a skill that..." }],
  "model": "anthropic/claude-sonnet-4"
}

Returns a streaming response (Server-Sent Events) via Vercel AI SDK's toDataStreamResponse(). Used with the useChat() hook on the client.

Skill Testing

Run Test

POST /api/test
Content-Type: application/json

{
  "skillId": "abc123",
  "model": "anthropic/claude-sonnet-4",
  "userMessage": "Review this PR",
  "arguments": { "FILE_PATH": "/src/index.ts" }
}

Returns a streaming response. On completion, a test_runs row is saved with token usage and latency metrics.

Export and Deploy

Export as Zip

POST /api/export
Content-Type: application/json

{
  "skillId": "abc123"
}

Returns a .zip file download containing the skill directory structure.

Deploy to Filesystem

POST /api/export/deploy
Content-Type: application/json

{
  "skillId": "abc123"
}

Writes the skill to ~/.claude/skills/<slug>/. Returns the deployed path.

Import

Import Skills

POST /api/import
Content-Type: multipart/form-data

# Upload a .zip file, or:
Content-Type: application/json

{
  "directory": "~/.claude/skills/"
}

Returns a list of discovered skills with validation results.

Settings

Get Settings

GET /api/settings

Returns app settings. The API key value is never included in the response.

Update Settings

PUT /api/settings
Content-Type: application/json

{
  "openrouterApiKey": "sk-or-...",
  "defaultModel": "anthropic/claude-sonnet-4",
  "theme": "dark"
}

The API key is encrypted before storage.

Models

List Models

GET /api/models

Returns available AI models from OpenRouter. Results are cached in the database.