API Reference

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
Public

No token required. Available to all callers.

Optional Auth

Works without auth; provides more features when authenticated.

Auth Required

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.

GET/api/v1/skills
Public

Search 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"
  }
}
GET/api/v1/skills/trending
Public

Get 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
    }
  ]
}
GET/api/v1/skills/:slug
Public

Get 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"
  }
}
POST/api/v1/skills/:slug/adopt
Optional Auth

Adopt 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
}
POST/api/v1/skills/:slug/improve
Auth Required

Analyze 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": "..."
}
POST/api/v1/skills
Auth Required

Publish 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.

POST/api/trpc/scan.analyze
Optional Auth

Analyze 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" }
    ]
  }
}
GET/api/trpc/scan.rules
Public

List 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
  },
  ...
]
POST/api/trpc/scan.save
Auth Required

Save 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" }
GET/api/trpc/scan.history
Optional Auth

Retrieve 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
}
GET/api/trpc/scan.getById
Optional Auth

Retrieve 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..."
}
GET/api/trpc/scan.compare
Optional Auth

Compare 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.

GET/api/trpc/academy.search
Public

Search 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
}
GET/api/trpc/academy.getBySlug
Public

Get 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": []
    }
  ]
}
GET/api/trpc/academy.trending
Public

Get 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"
    }
  ]
}
POST/api/trpc/academy.publish
Auth Required

Publish 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
}
POST/api/trpc/academy.update
Auth Required

Update 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..."
}
POST/api/trpc/academy.adopt
Auth Required

Adopt 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-..."
}
POST/api/trpc/academy.unadopt
Auth Required

Remove a skill from your adopted collection and decrement the skill's adoption counter.

Request Body

{ "skillId": "550e8400-..." }

Response

{ "success": true }
GET/api/trpc/academy.mySkills
Auth Required

List 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"
    }
  ]
}
GET/api/trpc/academy.myAdoptions
Auth Required

List 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
    }
  ]
}
POST/api/trpc/academy.improve
Auth Required

Analyze 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"
  }
}
GET/api/trpc/academy.requestSkill
Public

Describe 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
}
POST/api/trpc/academy.fork
Auth Required

Fork 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"
}
POST/api/trpc/academy.submitImprovement
Auth Required

Submit 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
}
POST/api/trpc/academy.reviewImprovement
Auth Required

Review 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
}
GET/api/trpc/academy.skillVersions
Public

Get 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
}
GET/api/trpc/academy.pendingImprovements
Auth Required

Get 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.

POST/api/trpc/converter.convert
Optional Auth

Convert 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
}
POST/api/trpc/converter.convertAndSave
Auth Required

Convert 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": [...]
}
GET/api/trpc/converter.detectPlatform
Optional Auth

Auto-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.

POST/api/trpc/coach.analyze
Auth Required

Get 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
}
GET/api/trpc/coach.usage
Optional Auth

Check 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"
}
GET/api/trpc/coach.history
Optional Auth

Get 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.

POST/api/trpc/soul.analyze
Optional Auth

Analyze 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)"
  ]
}
POST/api/trpc/soul.reportFeedback
Optional Auth

Report 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
}
GET/api/trpc/soul.insights
Public

Get 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.

GET/api/trpc/agentTokens.list
Auth Required

List 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..."
  }
]
POST/api/trpc/agentTokens.create
Auth Required

Generate 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"
}
POST/api/trpc/agentTokens.revoke
Auth Required

Revoke (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_scan

Scan content for security issues

ferretforge_convert

Convert between platform formats

ferretforge_platforms

List supported platforms

ferretforge_detect

Auto-detect platform format

ferretforge_academy_search

Search published skills

ferretforge_academy_get_skill

Get skill by slug

ferretforge_academy_trending

Get trending skills

ferretforge_academy_suggest

Get skill recommendations

ferretforge_academy_improve

Analyze and improve skills

ferretforge_academy_request

Request matching skills

ferretforge_academy_adopt

Adopt a skill

ferretforge_academy_publish

Publish a skill

ferretforge_soul_analyze

Analyze personality files

ferretforge_soul_improve

Improve soul content

Rate Limits

API rate limits are applied at multiple levels to ensure fair usage and protect system resources.

ScopeLimitWindow
Global API (per IP)100 requests1 minute
Coach (Free tier)5 sessions24 hours
Academy Improve (Free tier)5 analyses24 hours
Semantic Search (per user)50 queries24 hours
Semantic Search (global)500 queries24 hours
Content Size50 KBper request

Higher-tier plans (Starter, Pro, Enterprise) receive increased rate limits for Coach and Academy Improve endpoints. Check Pricing for plan details.