API Documentation
Complete reference for the FerretForge API. Includes the REST API v1 (simple JSON endpoints at /api/v1/) and the tRPC API (at /api/trpc/).
Authentication
FerretForge uses Bearer token authentication with tokens prefixed ff_. Tokens are generated from Settings > Agent API Keys in the dashboard.
HTTP Header
Authorization: Bearer ff_xxxxxxxxxxxxxxxxxxxx
Environment Variable
export FERRETFORGE_TOKEN=ff_xxxxxxxxxxxxxxxxxxxx
No token required. Available to all callers.
Works without auth; provides more features when authenticated.
Bearer token mandatory. Returns 401 without valid token.
tRPC Usage
The API uses tRPC 11 over HTTP. Queries use GET with URL-encoded input; mutations use POST with JSON body. All endpoints are accessible under /api/trpc/.
Query Example (GET)
GET /api/trpc/scan.rules # With input parameters (URL-encoded JSON): GET /api/trpc/academy.search?input=%7B%22query%22%3A%22typescript%22%7D
Mutation Example (POST)
POST /api/trpc/scan.analyze
Content-Type: application/json
Authorization: Bearer ff_xxxxxxxxxxxx
{
"content": "# My Skill\nYou are a helpful assistant...",
"platform": "claude-agent",
"filename": "skill.md"
}Batch Requests
# tRPC supports batch requests via comma-separated procedure names: GET /api/trpc/scan.rules,academy.trending # Each procedure result is returned in the same order as requested.
Response Format
{
"result": {
"data": { ... } // The actual response data
}
}
// Error response:
{
"error": {
"message": "Content exceeds 50KB limit",
"code": -32600,
"data": {
"code": "BAD_REQUEST",
"httpStatus": 400
}
}
}cURL Example
curl -X POST https://www.ferretforge.ai/api/trpc/scan.analyze \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ff_xxxxxxxxxxxx" \
-d '{
"content": "# My Skill\nYou are a helpful assistant...",
"platform": "claude-agent"
}'REST API v1
Simple JSON endpoints for agents and CLI tools. No tRPC client needed.
/api/v1/skillsSearch published skills with optional text query, platform filter, and pagination. Returns standard JSON.
Request Body
GET /api/v1/skills?q=typescript&platform=cursor-rule&limit=20&offset=0
Response
{
"items": [...],
"total": 42,
"_links": {
"self": "/api/v1/skills?q=typescript&limit=20&offset=0",
"next": "/api/v1/skills?q=typescript&limit=20&offset=20"
}
}/api/v1/skills/trendingGet the most-adopted skills, optionally filtered by platform.
Request Body
GET /api/v1/skills/trending?limit=10&platform=cursor-rule
Response
{
"items": [
{
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"compositeScore": 92.5,
"adoptionCount": 47
}
]
}/api/v1/skills/:slugGet full skill detail including content and all platform variants.
Response
{
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"content": "# TypeScript Code Review\n...",
"platform": "cursor-rule",
"variants": [
{ "platform": "claude-agent", "content": "...", "fidelityScore": 0.95 }
],
"_links": {
"self": "/api/v1/skills/ts-code-review",
"adopt": "/api/v1/skills/ts-code-review/adopt",
"web": "https://www.ferretforge.ai/academy/ts-code-review"
}
}/api/v1/skills/:slug/adoptAdopt a skill. Returns content for your target platform and recommended file path. Auth optional but recommended for adoption tracking.
Request Body
{
"platform": "cursor-rule"
}Response
{
"slug": "ts-code-review",
"content": "...",
"filePath": ".cursor/rules/ts-code-review.mdc",
"adopted": true
}/api/v1/skills/:slug/improveAnalyze skill content and get improvement suggestions. Requires Bearer token. Rate-limited per plan tier.
Request Body
{
"content": "# My Skill\n...",
"platform": "cursor-rule",
"structuralOnly": false
}Response
{
"scores": { ... },
"structuralHints": [...],
"suggestions": [...],
"improvedContent": "..."
}/api/v1/skillsPublish a new skill to the Academy. Requires Bearer token and Starter plan or above.
Request Body
{
"name": "TypeScript Code Review",
"slug": "ts-code-review",
"content": "# TypeScript Code Review\n...",
"platform": "cursor-rule",
"description": "Comprehensive review rules",
"category": "development",
"tags": ["typescript", "code-review"]
}Response
{
"id": "...",
"slug": "ts-code-review",
"compositeScore": 92.5
}Scanning
Security analysis, quality scoring, and MITRE ATT&CK mapping for AI skill content.
/api/trpc/scan.analyzeAnalyze skill content for security findings, intelligence quality, and platform fit. Returns scores, MITRE ATT&CK mapping, and detailed findings with line-level context. Results are persisted for authenticated users.
Request Body
{
"content": "# My Agent Skill\nYou are a helpful assistant...",
"filename": "skill.md",
"platform": "claude-agent"
}Response
{
"findings": [
{
"ruleId": "CRED-001",
"ruleName": "Hardcoded API Key",
"severity": "CRITICAL",
"category": "credentials",
"line": 12,
"match": "sk-...",
"remediation": "Remove hardcoded API key",
"riskScore": 95,
"context": [...]
}
],
"securityScore": { "score": 72, "grade": "C" },
"intelligenceScore": { "score": 85, "grade": "B" },
"platformScore": { "score": 90, "grade": "A" },
"platform": "claude-agent",
"scanDuration": 42,
"mitreReport": {
"techniques": [
{ "id": "T1552", "name": "Unsecured Credentials", "tactic": "Credential Access" }
]
}
}/api/trpc/scan.rulesList all available security scan rules with their ID, name, category, severity, description, and enabled status. Returns 80+ rules across 11 threat categories.
Response
[
{
"id": "CRED-001",
"name": "Hardcoded API Key",
"category": "credentials",
"severity": "CRITICAL",
"description": "Detects hardcoded API keys and secrets",
"enabled": true
},
...
]/api/trpc/scan.saveSave a scan result to the authenticated user's history for later reference.
Request Body
{
"content": "# My Skill\n...",
"platform": "cursor-rule",
"score": 85
}Response
{ "id": "550e8400-e29b-41d4-a716-446655440000" }/api/trpc/scan.historyRetrieve the authenticated user's scan history with pagination. Returns scan results ordered by most recent.
Request Body
{
"limit": 20,
"offset": 0
}Response
{
"items": [
{
"id": "...",
"platform": "claude-agent",
"securityScore": 95,
"intelligenceScore": 80,
"createdAt": "2026-02-20T..."
}
],
"total": 42
}/api/trpc/scan.getByIdRetrieve a single scan result by ID. Only returns results belonging to the authenticated user.
Request Body
{ "id": "550e8400-e29b-41d4-a716-446655440000" }Response
{
"id": "...",
"content": "...",
"platform": "cursor-rule",
"securityScore": 92,
"intelligenceScore": 88,
"platformScore": 95,
"findingsJson": [...],
"complianceJson": {...},
"mitreJson": {...},
"createdAt": "2026-02-20T..."
}/api/trpc/scan.compareCompare two scan results to see resolved and new findings, score deltas, and improvement trends.
Request Body
{
"beforeId": "550e8400-...",
"afterId": "660f9500-..."
}Response
{
"scoreDelta": 12,
"findingsResolved": [...],
"findingsNew": [...],
"beforeScore": 78,
"afterScore": 90,
"intelDelta": 5
}Academy
Browse, publish, adopt, fork, and improve AI skills in the curated skill marketplace.
/api/trpc/academy.searchSearch published skills with optional text query, platform filter, and category filter. Supports semantic vector search for authenticated users. Results sorted by composite score.
Request Body
{
"query": "typescript code review",
"platform": "cursor-rule",
"category": "development",
"limit": 20,
"offset": 0
}Response
{
"items": [
{
"id": "...",
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"description": "Comprehensive review rules...",
"platform": "cursor-rule",
"compositeScore": 92.5,
"adoptionCount": 47,
"status": "published"
}
],
"total": 15
}/api/trpc/academy.getBySlugGet a single skill by its slug, including full content and cross-platform variants. Public skills are visible to all; private skills require ownership or admin role.
Request Body
{ "slug": "ts-code-review" }Response
{
"id": "...",
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"content": "# TypeScript Code Review\n...",
"platform": "cursor-rule",
"securityScore": 100,
"intelligenceScore": 88,
"compositeScore": 92.5,
"variants": [
{
"targetPlatform": "claude-agent",
"content": "...",
"fidelityScore": 0.95,
"warnings": []
}
]
}/api/trpc/academy.trendingGet trending skills ordered by adoption count. Returns the most popular skills in the marketplace.
Request Body
{ "limit": 10 }Response
{
"items": [
{
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"compositeScore": 92.5,
"adoptionCount": 47,
"platform": "cursor-rule"
}
]
}/api/trpc/academy.publishPublish a new skill to the Academy. Content is security-scanned and quality-scored. Requires a perfect security score (100/100) to pass the security gate. Automatically generates cross-platform variants for all 17 platforms.
Request Body
{
"name": "TypeScript Code Review",
"slug": "ts-code-review",
"description": "Comprehensive code review rules",
"content": "# TypeScript Code Review\n...",
"platform": "cursor-rule",
"category": "development",
"tags": ["typescript", "code-review"],
"license": "open",
"source": "community",
"sourceUrl": "https://github.com/..."
}Response
{
"id": "...",
"slug": "ts-code-review",
"compositeScore": 92.5,
"securityScore": 100,
"variantCount": 16
}/api/trpc/academy.updateUpdate an existing skill. Only the original author can update. If content is changed, the skill is re-scored and must pass the security gate again. A new version record is created and variants are regenerated.
Request Body
{
"id": "550e8400-...",
"content": "# Updated Content\n...",
"description": "Updated description",
"tags": ["typescript", "code-review", "v2"],
"changeSummary": "Added error handling section"
}Response
{
"id": "...",
"versionNumber": 2,
"compositeScore": 94.1,
"updatedAt": "2026-02-21T..."
}/api/trpc/academy.adoptAdopt a published skill to add it to your collection. Increments the skill's adoption counter and notifies the author.
Request Body
{
"skillId": "550e8400-...",
"platform": "cursor-rule"
}Response
{
"id": "adoption-uuid",
"skillId": "550e8400-..."
}/api/trpc/academy.unadoptRemove a skill from your adopted collection and decrement the skill's adoption counter.
Request Body
{ "skillId": "550e8400-..." }Response
{ "success": true }/api/trpc/academy.mySkillsList all skills published by the authenticated user, ordered by most recently updated.
Response
{
"items": [
{
"id": "...",
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"compositeScore": 92.5,
"adoptionCount": 47,
"status": "published"
}
]
}/api/trpc/academy.myAdoptionsList all skills adopted by the authenticated user, including full content. Ordered by adoption date.
Response
{
"items": [
{
"adoptionId": "...",
"adoptedAt": "2026-02-20T...",
"skillId": "...",
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"content": "...",
"compositeScore": 92.5
}
]
}/api/trpc/academy.improveAnalyze skill content and get improvement suggestions. Two-layer analysis: Layer 1 (scoring, findings, structural hints) always works. Layer 2 (LLM-powered suggestions) requires a configured provider key. Rate-limited per plan tier.
Request Body
{
"content": "# My Skill\n...",
"platform": "cursor-rule",
"structuralOnly": false
}Response
{
"scores": {
"securityScore": 100,
"intelligenceScore": 72,
"platformFitScore": 85,
"compositeScore": 85.1
},
"findings": [...],
"structuralHints": [
{
"category": "quality",
"priority": "medium",
"title": "Include examples",
"detail": "Add concrete examples..."
}
],
"suggestions": [
{
"category": "clarity",
"title": "Add section headings",
"current": "...",
"improved": "...",
"explanation": "...",
"priority": "high"
}
],
"improvedContent": "# Improved Skill\n...",
"overallAssessment": "Good foundation...",
"llmAvailable": true,
"rateLimit": {
"remaining": 4,
"limit": 5,
"resetAt": "2026-02-22T00:00:00Z"
}
}/api/trpc/academy.requestSkillDescribe what you need in natural language. Returns matching published skills or a scaffold template if no good matches exist.
Request Body
{
"description": "code review rules for TypeScript projects",
"platform": "cursor-rule",
"category": "development"
}Response
{
"description": "code review rules for TypeScript projects",
"matches": [
{
"slug": "ts-code-review",
"name": "TypeScript Code Review",
"compositeScore": 92.5,
"adoptionCount": 47,
"adoptCommand": "ferretforge academy adopt ts-code-review",
"webUrl": "https://www.ferretforge.ai/academy/ts-code-review"
}
],
"scaffold": null
}/api/trpc/academy.forkFork a published skill into a draft owned by the current user. Requires Starter plan or above. The original author is notified.
Request Body
{
"skillId": "550e8400-...",
"slug": "my-ts-review-fork",
"name": "My TS Review (customized)"
}Response
{
"id": "new-fork-uuid",
"slug": "my-ts-review-fork"
}/api/trpc/academy.submitImprovementSubmit an improvement proposal for a published skill. The improved content must pass the security gate and increase the composite score. The skill author reviews and can approve or reject.
Request Body
{
"skillId": "550e8400-...",
"title": "Add error handling section",
"description": "Added comprehensive error handling guidance",
"category": "enhancement",
"improvedContent": "# Improved Skill\n..."
}Response
{
"id": "request-uuid",
"compositeScore": 94.1
}/api/trpc/academy.reviewImprovementReview and approve or reject an improvement request. Only the skill author can review. Approved improvements are automatically merged with a new version.
Request Body
{
"requestId": "request-uuid",
"action": "approve",
"reviewNotes": "Great improvement, merging!"
}Response
{
"status": "merged",
"newVersion": 3
}/api/trpc/academy.skillVersionsGet the version history for a skill. Authors and admins see full details; other users see only the latest version number.
Request Body
{ "skillId": "550e8400-..." }Response
{
"versions": [
{
"id": "version-uuid",
"versionNumber": 3,
"changeSummary": "Merged improvement: Add error handling",
"compositeScore": 94.1,
"createdAt": "2026-02-21T..."
}
],
"restricted": false
}/api/trpc/academy.pendingImprovementsGet pending improvement requests for skills authored by the current user. Useful for reviewing community contributions.
Response
{
"items": [
{
"id": "...",
"skillId": "...",
"title": "Add error handling section",
"compositeScore": 94.1,
"currentCompositeScore": 92.5,
"status": "pending",
"skillName": "TypeScript Code Review"
}
]
}Converter
Cross-platform format conversion with fidelity scoring and loss reporting.
/api/trpc/converter.convertConvert skill content from one platform format to another. Supports all 17 platforms. Returns converted content, fidelity score, warnings, and lossy field details.
Request Body
{
"content": "# My Cursor Rule\n...",
"fromPlatform": "cursor-rule",
"toPlatform": "claude-agent"
}Response
{
"content": "# Converted Agent Skill\n...",
"warnings": ["Some Cursor-specific directives were simplified"],
"lossyFields": ["cursorSpecificConfig"],
"fieldLossDetails": [...],
"fidelityScore": 0.92
}/api/trpc/converter.convertAndSaveConvert skill content and save the result as a new standalone document in the user's library.
Request Body
{
"content": "# My Cursor Rule\n...",
"fromPlatform": "cursor-rule",
"toPlatform": "claude-agent",
"filename": "my-skill-claude.md",
"tags": ["converted", "claude"],
"description": "Converted from Cursor format"
}Response
{
"documentId": "doc-uuid",
"content": "# Converted Agent Skill\n...",
"fidelityScore": 0.92,
"warnings": [...]
}/api/trpc/converter.detectPlatformAuto-detect the platform format of skill content based on content analysis and optional filename. Returns the detected platform ID and a confidence score.
Request Body
{
"content": "rules:\n - pattern: ...",
"filename": ".cursorrules"
}Response
{
"platform": "cursor-rule",
"confidence": 0.95
}Coach
AI-powered coaching with LLM analysis, suggestions, and rate-limited usage per plan tier.
/api/trpc/coach.analyzeGet AI-powered coaching suggestions for skill content. Uses configured LLM provider (OpenAI, Anthropic, Groq, or OpenRouter). Rate-limited and cost-budget-tracked per user plan tier.
Request Body
{
"content": "# My Agent Skill\n...",
"platform": "claude-agent",
"findings": [
{
"ruleName": "Vague Instructions",
"severity": "MEDIUM",
"line": 5
}
]
}Response
{
"suggestions": [
{
"category": "clarity",
"priority": "high",
"line": 5,
"title": "Be more specific",
"explanation": "Replace vague instruction...",
"currentText": "Handle errors",
"suggestedText": "When an error occurs, log the error message..."
}
],
"overallAssessment": "Good foundation with room for improvement...",
"model": "gpt-4o-mini",
"tier": "free",
"duration": 1250
}/api/trpc/coach.usageCheck the current user's remaining coaching sessions for the day, limit, reset time, and plan tier.
Response
{
"remaining": 4,
"limit": 5,
"resetAt": "2026-02-22T00:00:00Z",
"plan": "free"
}/api/trpc/coach.historyGet the authenticated user's recent coaching session history.
Request Body
{ "limit": 10 }Response
[
{
"id": "...",
"platform": "cursor-rule",
"model": "gpt-4o-mini",
"duration": 1250,
"suggestionsJson": [...],
"createdAt": "2026-02-20T..."
}
]Soul Analyzer
Personality/soul file analysis with PII sanitization, 4-dimension scoring, and self-improving suggestion templates.
/api/trpc/soul.analyzeAnalyze a soul/personality file. Automatically sanitizes PII before scoring. Scores across 4 dimensions: clarity, boundaries, consistency, and evolution. Returns weighted suggestions filtered by learned effectiveness (SkillRL pattern). Never echoes back content.
Request Body
{
"content": "# My Agent Personality\nYou are a helpful assistant...",
"sectionHint": "identity"
}Response
{
"score": 78,
"grade": "B",
"dimensions": {
"clarity": 22,
"boundaries": 18,
"consistency": 20,
"evolution": 18
},
"breakdown": [...],
"sectionMap": [
{ "name": "identity", "detected": true },
{ "name": "boundaries", "detected": false },
{ "name": "tone", "detected": true }
],
"suggestions": [
{
"templateId": "add-boundaries",
"dimension": "boundaries",
"title": "Define clear boundaries",
"description": "Add explicit boundaries...",
"priority": "high",
"weight": 0.85
}
],
"detectedMistakes": [...],
"piiWarning": true,
"piiCategories": ["email", "phone"],
"redactionCount": 3,
"insights": [
"Your clarity score is above average (avg: 18/25)"
]
}/api/trpc/soul.reportFeedbackReport feedback after applying soul analysis suggestions. Updates template effectiveness scores using SkillRL-inspired rolling averages. This feedback loop improves suggestion quality over time.
Request Body
{
"feedback": [
{
"templateId": "add-boundaries",
"dimension": "boundaries",
"scoreBefore": 18,
"scoreAfter": 23,
"applied": true
}
]
}Response
{
"recorded": 1,
"appliedCount": 1,
"averageScoreDelta": 5.0
}/api/trpc/soul.insightsGet aggregate public insights from all soul analyses. Includes average scores, common patterns, and template effectiveness rankings.
Response
{
"totalAnalyses": 1250,
"averageScores": {
"composite": 72,
"clarity": 19,
"boundaries": 15,
"consistency": 20,
"evolution": 18
},
"patterns": {
"pctMissingBoundaries": 0.62,
"pctPiiDetected": 0.18
},
"templateEffectiveness": [
{
"templateId": "add-boundaries",
"effectiveness": 0.85,
"sampleCount": 340
}
]
}Agent Tokens
Manage API tokens for agent access. Tokens use the ff_ prefix and are hashed at rest.
/api/trpc/agentTokens.listList all active agent tokens for the current user. Returns safe fields only (prefix, name, last used). Never exposes the full token.
Response
[
{
"id": "token-uuid",
"name": "My CI Agent",
"tokenPrefix": "ff_abc12",
"lastUsedAt": "2026-02-20T...",
"createdAt": "2026-01-15T..."
}
]/api/trpc/agentTokens.createGenerate a new agent API token. The plain token is returned ONCE and cannot be retrieved again. Store it securely.
Request Body
{ "name": "My CI Agent" }Response
{
"plainToken": "ff_abc123def456ghi789...",
"tokenPrefix": "ff_abc12"
}/api/trpc/agentTokens.revokeRevoke (soft-delete) an agent token. The token will immediately stop working for API authentication.
Request Body
{ "id": "token-uuid" }Response
{ "success": true }MCP Server Integration
FerretForge provides a Model Context Protocol (MCP) server that exposes all scanning, conversion, and Academy features as tools for AI agents like Claude Code.
Installation
npx @ferretforge/mcp
Claude Code Configuration
{
"mcpServers": {
"ferretforge": {
"command": "npx",
"args": ["@ferretforge/mcp"],
"env": {
"FERRETFORGE_TOKEN": "ff_xxxxxxxxxxxx"
}
}
}
}Available MCP Tools
ferretforge_scanScan content for security issues
ferretforge_convertConvert between platform formats
ferretforge_platformsList supported platforms
ferretforge_detectAuto-detect platform format
ferretforge_academy_searchSearch published skills
ferretforge_academy_get_skillGet skill by slug
ferretforge_academy_trendingGet trending skills
ferretforge_academy_suggestGet skill recommendations
ferretforge_academy_improveAnalyze and improve skills
ferretforge_academy_requestRequest matching skills
ferretforge_academy_adoptAdopt a skill
ferretforge_academy_publishPublish a skill
ferretforge_soul_analyzeAnalyze personality files
ferretforge_soul_improveImprove soul content
Rate Limits
API rate limits are applied at multiple levels to ensure fair usage and protect system resources.
| Scope | Limit | Window |
|---|---|---|
| Global API (per IP) | 100 requests | 1 minute |
| Coach (Free tier) | 5 sessions | 24 hours |
| Academy Improve (Free tier) | 5 analyses | 24 hours |
| Semantic Search (per user) | 50 queries | 24 hours |
| Semantic Search (global) | 500 queries | 24 hours |
| Content Size | 50 KB | per request |
Higher-tier plans (Starter, Pro, Enterprise) receive increased rate limits for Coach and Academy Improve endpoints. Check Pricing for plan details.