API.md

API Reference

SkillForge exposes a REST API with three tiers: public, authenticated, and admin.

Auto-generated OpenAPI 3.0 spec available at GET /api/openapi.json when the server is running.

---

Public Endpoints (no auth)

Method	Endpoint	Description
GET	/api/health	Health check with readiness and capability diagnostics
GET	/api/skills	List all registered skills
GET	/api/skills/:name	Skill detail with actions and triggers
GET	/api/skills/:name/actions	Action schemas for a skill
GET	/api/flags	List feature flags
GET	/api/flags/:name	Evaluate a specific flag
POST	/api/webhook/:skill/:trigger	Incoming webhook trigger
GET	/api/events/log	Event bus log
GET	/api/events	Event subscriptions
GET	/api/openapi.json	Auto-generated OpenAPI 3.0 spec

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login with username/password, returns JWT + refresh token
GET	/api/auth/me	Get current user info (any authenticated role)

Admin Endpoints (JWT required, role-based)

Method	Endpoint	Required Role	Description
POST	/api/admin/token	secret in body	Generate JWT (headless fallback)
POST	/api/admin/sse-token	any	Short-lived SSE token (5min)
POST	/api/admin/run	admin, operator	Execute any skill action
POST	/api/admin/credentials	admin	Store encrypted credentials
DELETE	/api/admin/credentials/:skill/:cred	admin	Delete credentials
POST	/api/admin/pipeline/run	admin, operator	Run multi-step pipeline
GET	/api/admin/logs	admin, operator, viewer	Execution logs
GET	/api/admin/users	admin	List users
POST	/api/admin/users	admin	Create user
PUT	/api/admin/users/:id/role	admin	Change user role
DELETE	/api/admin/users/:id	admin	Delete user
PUT	/api/admin/skills/:name/toggle	admin	Enable/disable skill
DELETE	/api/admin/skills/:name	admin	Delete skill

Real-Time (SSE)

Method	Endpoint	Description
GET	/api/events/stream?token=<sse-token>	SSE stream for live events, logs, stats

MCP Endpoints

Method	Endpoint	Description
GET	/api/mcp/tools	List MCP-exposed tools
GET	/api/mcp/resources	List MCP resources
GET	/api/mcp/prompts	List MCP prompts

Goals (experimental, JWT required)

Method	Endpoint	Description
GET	/api/admin/goals	List goal definitions
POST	/api/admin/goals	Create goal definition
PUT	/api/admin/goals/:id	Update goal definition
DELETE	/api/admin/goals/:id	Delete goal definition
POST	/api/admin/goals/:id/run	Start a goal run
GET	/api/admin/goals/:id/runs	List runs for a goal
GET	/api/admin/goals/runs/:runId	Get run details
POST	/api/admin/goals/runs/:runId/cancel	Cancel a running goal
GET	/api/admin/goals/templates/list	List goal templates
POST	/api/admin/goals/from-template	Create goal from template