# SkillForge — Full API Documentation for AI Agents

## Overview
SkillForge converts YouTube videos into structured, reusable AI skills. Each skill captures a creator's exact methodology as an executable tool: workflow steps, principles, required inputs, pitfalls, examples, and glossary.

## Authentication
All authenticated endpoints accept: Authorization: Bearer sk-sf_<48hex>
Generate keys at: https://skillforge.digital/app/settings
Keys inherit the plan limits of the user who created them.

## Plans
  - Free ($0): 3 forges/month
  - Creator ($19.99/mo): unlimited forges/month, private library

---

## Endpoints

### GET /api/agents/pricing
No auth required. Returns machine-readable plan details.
Response: { plans: [{ id, name, price_usd, interval, limits, features }], currency, trial_days }

### GET /api/agents/tools
No auth required. Discover all available skills as invocable tools.
Query params: category (method|framework|template|knowledge), tag, creator, query, limit (1-100), offset
Response: { tools: [{ name, display_name, description, category, tags, creator, apply_url, inputs }], total, limit, offset }

### POST /api/agents/tools/{channel}/{skillName}/apply
Auth required. Apply a skill to a scenario.
Body: { "scenario": "string (required)", "inputs": { "key": "value" } }
Response: { skill: { id, slug, name, category, creator, url }, coaching_prompt: "string", mode: "coaching" }
The coaching_prompt is a complete instruction set for walking through the skill methodology in context.

### GET /api/agents/recommendations/{channel}/{skillName}
No auth required. Get recommendation signals for a skill.
Response: { skill_slug, skill_name, total_applies, unique_agents, average_rating, recent_scenarios }

### POST /api/skills
Auth required. Forge a new skill from a YouTube video.
Body: { "videoId": "string", "url": "string", "title?": "string", "channel?": "string" }
Response (202): { skillId, status: "queued" }
The forge runs async (30-90s). Poll GET /api/skills or register a webhook.

### GET /api/skills
Auth required. List the authenticated user's skills.
Response: [{ id, slug, name, status, category, ... }]

### GET /api/agents/usage
Auth required. Get usage and subscription status.
Response: { plan, forges_used_this_month, forges_remaining, subscription_status, current_period_end, recent_forges }

### GET /api/agents/subscription
Auth required. Get subscription details.
Response: { plan, subscription: { id, status, current_period_end, cancel_at_period_end, trial_end } | null }

### POST /api/agents/subscribe
Auth required. Create a checkout session for upgrading.
Body: { "planId": "creator", "interval": "monthly" }
Response: { checkout_url, plan, interval, message }
The checkout_url must be opened by a human to complete payment.

### POST /api/agents/webhooks
Auth required. Register a webhook callback.
Body: { "url": "https://...", "events": ["forge.completed", "forge.failed", "subscription.updated"] }
Response (201): { id, url, events, secret }
The secret is shown once. Deliveries include X-SkillForge-Signature (HMAC-SHA256 of body with secret).

### GET /api/agents/webhooks
Auth required. List registered webhooks.

### DELETE /api/agents/webhooks/{id}
Auth required. Remove a webhook.

### GET /api/agents/preferences
Auth required. Get agent preferences/memory.
Response: { default_category, default_output_format, skill_collections, custom_metadata }

### PUT /api/agents/preferences
Auth required. Update agent preferences (partial merge).
Body: { "default_category?": "framework", "skill_collections?": [...], "custom_metadata?": {...} }

### POST /api/agents/keys
Cookie auth only (dashboard). Generate a new API key.
Body: { "name?": "string" }
Response (201): { id, name, key, key_prefix, created_at }
The full key is returned once.

### GET /api/agents/keys
Cookie auth only. List API keys.

### DELETE /api/agents/keys
Cookie auth only. Revoke a key.
Body: { "keyId": "uuid" }

---

## Webhook Events
- forge.completed: { skill_id, skill_name, slug, status, source_url }
- forge.failed: { skill_id, error }
- subscription.updated: { status, plan }

## Error Codes
- 401: Missing or invalid authentication
- 403: Plan limit reached (include plan, used, limit in response)
- 404: Skill not found
- 429: Rate limit exceeded
- 500: Server error

## Rate Limits
Free plan: 3 forges/month. Creator plan: unlimited. API requests: 100/minute per key.

## Contact
- General enquiries: team@skillforge.digital
- Technical / API support: cto@skillforge.digital
- Product feedback: cpo@skillforge.digital
- Customer support: cco@skillforge.digital
- Partnerships & press: cmo@skillforge.digital
- Billing & pricing: cfo@skillforge.digital
- CEO: ceo@skillforge.digital

## Source
https://skillforge.digital
https://skillforge.digital/agents