Agent Forge API Documentation

Integrate Agent Forge into your workflow with our REST API and MCP server.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

curl -H "Authorization: Bearer af_..." \
  https://specient.com/api/v1/files

API keys are prefixed with af_. Keep them secret. If a key is compromised, revoke it immediately from your dashboard.

Endpoints

GET/api/v1/files

List agent files belonging to the authenticated user. Returns paginated results sorted by most recently updated.

Parameters

Name	Type	In	Description
page	integer	query	Page number (default: 1)
per_page	integer	query	Results per page, max 100 (default: 20)
domain	string	query	Filter by domain taxonomy slug

Example Request

curl -H "Authorization: Bearer af_..." \
  "https://specient.com/api/v1/files?page=1&per_page=10"

Example Response

{
  "data": [
    {
      "id": "file_abc123",
      "name": "CLAUDE.md",
      "score": 17,
      "star_tier": 4,
      "domain": "software-engineering",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 42
  }
}

GET/api/v1/files/:id

Get full details for a single agent file, including the latest analysis result and version history.

Parameters

Name	Type	In	Description
id	string	path	File ID (e.g. file_abc123)

Example Request

curl -H "Authorization: Bearer af_..." \
  https://specient.com/api/v1/files/file_abc123

Example Response

{
  "id": "file_abc123",
  "name": "CLAUDE.md",
  "content": "# Project Instructions\n...",
  "score": 17,
  "star_tier": 4,
  "domain": "software-engineering",
  "rubric": {
    "structure": 5,
    "reasoning": 4,
    "control": 4,
    "engagement": 4
  },
  "versions": 3,
  "created_at": "2026-03-15T08:00:00Z",
  "updated_at": "2026-04-01T12:00:00Z"
}

GET/api/v1/files/:id/score

Get the score and star tier for a file without the full content. Lightweight endpoint for dashboards and badges.

Parameters

Name	Type	In	Description
id	string	path	File ID

Example Request

curl -H "Authorization: Bearer af_..." \
  https://specient.com/api/v1/files/file_abc123/score

Example Response

{
  "id": "file_abc123",
  "score": 17,
  "star_tier": 4,
  "percentile": 92,
  "rubric": {
    "structure": 5,
    "reasoning": 4,
    "control": 4,
    "engagement": 4
  }
}

POST/api/v1/files

Upload and analyze an agent file. The file content is scored against the 20-point rubric and stored in your account.

Parameters

Name	Type	In	Description
file_content	string	body	The full text content of the agent file
file_name	string	body	Original filename (e.g. CLAUDE.md, .cursorrules)
visibility	string	body	"private" or "public" (default: "private")

Example Request

curl -X POST \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_content": "# Project Instructions\n...",
    "file_name": "CLAUDE.md",
    "visibility": "public"
  }' \
  https://specient.com/api/v1/files

Example Response

{
  "id": "file_xyz789",
  "name": "CLAUDE.md",
  "score": 15,
  "star_tier": 3,
  "domain": "software-engineering",
  "rubric": {
    "structure": 4,
    "reasoning": 4,
    "control": 4,
    "engagement": 3
  },
  "created_at": "2026-04-05T10:30:00Z"
}

POST/api/v1/telemetry

Report usage telemetry for an agent file. Track how your file performs in real-world agent sessions.

Parameters

Name	Type	In	Description
file_id	string	body	The file ID to report against
event	string	body	Event type: "session_start", "session_end", "error", "feedback"
metadata	object	body	Optional key-value metadata (e.g. llm_provider, duration_ms)

Example Request

curl -X POST \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_abc123",
    "event": "session_end",
    "metadata": {
      "llm_provider": "anthropic",
      "duration_ms": 45200,
      "success": true
    }
  }' \
  https://specient.com/api/v1/telemetry

Example Response

{
  "ok": true,
  "event_id": "evt_abc123"
}

MCP Integration

Agent Forge also supports the Model Context Protocol (MCP), allowing AI agents to access your stored files directly during sessions.

Protocol

The MCP server uses JSON-RPC 2.0 over HTTP. All requests go to a single endpoint:

POST/api/mcp

Authentication uses the same Bearer token as the REST API.

Available Tools

Tool	Description
get_agent_file	Retrieve a stored agent file by ID. Returns content, score, and metadata.
list_agent_files	List all agent files for the authenticated user with optional filtering.
report_telemetry	Submit a telemetry event for usage tracking and analytics.
get_score	Get the current score and rubric breakdown for a file.

Example Request

curl -X POST \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_agent_file",
      "arguments": { "file_id": "file_abc123" }
    }
  }' \
  https://specient.com/api/mcp

Claude Code Configuration

Add Agent Forge as an MCP server in your ~/.claude/settings.json:

{
  "mcpServers": {
    "agent-forge": {
      "type": "http",
      "url": "https://specient.com/api/mcp",
      "headers": {
        "Authorization": "Bearer af_your_api_key_here"
      }
    }
  }
}

Rate Limits

Rate limits are applied per API key. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

Plan	Limit
Free	60 requests / minute
Pro	300 requests / minute
Enterprise	Custom