REST API Reference

Complete REST API documentation for Skill Engine HTTP server.

Base URL

When running skill serve --http:

http://localhost:3000/api

Interactive Documentation

Skill Engine provides interactive API documentation via Swagger UI:

When server is running:

• Swagger UI: http://localhost:3000/docs/api
• OpenAPI Spec: http://localhost:3000/api/openapi.json

Authentication

Currently no authentication required for local development. API key authentication coming in future versions.

Endpoints

Skills

List Skills

GET /api/skills

Returns all installed skills.

Response:

{
  "skills": [
    {
      "name": "kubernetes",
      "description": "Kubernetes cluster management",
      "runtime": "native",
      "tools": [...]
    }
  ]
}

Get Skill Details

GET /api/skills/{name}

Response:

{
  "name": "kubernetes",
  "description": "Kubernetes cluster management",
  "runtime": "native",
  "tools": [
    {
      "name": "get",
      "description": "Get Kubernetes resources",
      "parameters": [...]
    }
  ]
}

Execution

Execute Tool

POST /api/execute

Request:

{
  "skill_name": "kubernetes",
  "tool_name": "get",
  "parameters": {
    "resource": "pods",
    "namespace": "default"
  }
}

Response:

{
  "execution_id": "exec_123",
  "status": "success",
  "output": "{...}",
  "duration_ms": 245
}

List Executions

GET /api/executions?limit=10&offset=0

Response:

{
  "executions": [
    {
      "id": "exec_123",
      "skill_name": "kubernetes",
      "tool_name": "get",
      "status": "success",
      "created_at": "2024-01-15T10:30:00Z",
      "duration_ms": 245
    }
  ],
  "total": 100
}

Get Execution

GET /api/executions/{id}

Search

Semantic Search

POST /api/search

Request:

{
  "query": "deploy to kubernetes",
  "top_k": 10
}

Response:

{
  "results": [
    {
      "skill_name": "kubernetes",
      "tool_name": "apply",
      "description": "Apply Kubernetes manifests",
      "score": 0.95
    }
  ]
}

Health

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "version": "0.3.0",
  "uptime_seconds": 1234
}

Version Info

GET /api/version

Response:

{
  "version": "0.3.0",
  "commit": "abc123",
  "build_date": "2024-01-15"
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "TOOL_EXECUTION_FAILED",
    "message": "Tool execution failed: kubectl not found",
    "details": {
      "skill": "kubernetes",
      "tool": "get"
    }
  }
}

Error Codes:

• SKILL_NOT_FOUND: Skill doesn't exist
• TOOL_NOT_FOUND: Tool doesn't exist
• INVALID_PARAMETERS: Invalid tool parameters
• TOOL_EXECUTION_FAILED: Tool execution failed
• TIMEOUT: Execution timeout

Rate Limiting

Default limits:

• 1000 requests per minute
• 10000 requests per hour

Configurable via server options.

CORS

CORS enabled by default for local development. Configure for production use.

WebSocket Support

Coming soon for streaming execution output.

Examples

cURL

# List skills
curl http://localhost:3000/api/skills

# Execute tool
curl -X POST http://localhost:3000/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "skill_name": "kubernetes",
    "tool_name": "get",
    "parameters": {"resource": "pods"}
  }'

JavaScript/TypeScript

const response = await fetch('http://localhost:3000/api/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    skill_name: 'kubernetes',
    tool_name: 'get',
    parameters: { resource: 'pods' }
  })
});

const result = await response.json();
console.log(result);

Python

import requests

response = requests.post('http://localhost:3000/api/execute', json={
    'skill_name': 'kubernetes',
    'tool_name': 'get',
    'parameters': {'resource': 'pods'}
})

print(response.json())

See Also

• CLI Reference
• MCP Protocol
• OpenAPI Specification (when server running)