Documentation

Clawmit is an agent registry and version control system for AI agents. This documentation covers everything you need to build, deploy, and manage agents at scale.

Base URL

https://clawmit.xyz/api

All API requests should be made to this base URL.

Quick Start

Create an account

curl -X POST https://clawmit.xyz/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

Login to get a token

curl -X POST https://clawmit.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

Create your first agent

curl -X POST https://clawmit.xyz/api/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "description": "A helpful assistant",
    "prompt": "You are a helpful AI assistant.",
    "tools": [],
    "config": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

Authentication

Clawmit supports two authentication methods: JWT tokens for user sessions and API keys for programmatic access.

JWT Authentication

Obtain a JWT token by logging in with your credentials:

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_123",
    "email": "you@example.com"
  }
}

API Key Authentication

Create an API key from the dashboard for programmatic access with specific scopes:

POST /api/api-keys
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "Production API Key",
  "scopes": ["agents:read", "agents:write", "tasks:read", "tasks:write"]
}

Response:
{
  "id": "key_abc123",
  "key": "fc_live_1234567890abcdef...",
  "keyPrefix": "fc_live_12",
  "name": "Production API Key",
  "scopes": ["agents:read", "agents:write", "tasks:read", "tasks:write"]
}

Important: Store API keys securely. They are only shown once during creation.

Include authentication in all API requests:

curl https://clawmit.xyz/api/agents \
  -H "Authorization: Bearer YOUR_TOKEN_OR_API_KEY"

Agents

Agents are the core entity in Clawmit. Each agent has a configuration including prompts, tools, and settings.

List Agents

GET /api/agents?page=1&limit=10

Response:
{
  "data": [
    {
      "id": "agent_123",
      "name": "Support Assistant",
      "description": "Handles customer support",
      "status": "idle",
      "currentVersionId": "ver_456",
      "forkCount": 3,
      "createdAt": "2026-01-20T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

Create Agent

POST /api/agents
Content-Type: application/json

{
  "name": "Code Review Agent",
  "description": "Reviews pull requests",
  "prompt": "You are an expert code reviewer...",
  "tools": [
    {
      "name": "github_api",
      "description": "GitHub API access",
      "parameters": {
        "repo": "string",
        "pr_number": "number"
      }
    }
  ],
  "config": {
    "temperature": 0.3,
    "maxTokens": 4000
  }
}

Response:
{
  "id": "agent_789",
  "name": "Code Review Agent",
  "status": "idle",
  "currentVersionId": "ver_101",
  "currentVersion": {
    "id": "ver_101",
    "versionNumber": 1,
    "prompt": "You are an expert code reviewer...",
    "tools": [...],
    "config": {...}
  }
}

Get Agent Details

GET /api/agents/:id

Response:
{
  "id": "agent_123",
  "name": "Support Assistant",
  "description": "Handles customer support",
  "status": "idle",
  "currentVersionId": "ver_456",
  "currentVersion": {
    "id": "ver_456",
    "versionNumber": 5,
    "prompt": "...",
    "tools": [...],
    "config": {...}
  },
  "forkCount": 3,
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-02-01T14:30:00Z"
}

Fork Agent

Create a fork of an existing agent with three fork types:

exact_clone - Perfect copy of the agent
prompt_mutation - Fork with modified prompt
tool_mutation - Fork with modified tools/config

POST /api/agents/:id/fork
Content-Type: application/json

{
  "forkType": "prompt_mutation",
  "name": "Support Assistant (Spanish)",
  "prompt": "Eres un asistente de soporte...",
  "commitMessage": "Spanish language version"
}

Response:
{
  "id": "agent_999",
  "name": "Support Assistant (Spanish)",
  "parentAgent": {
    "id": "agent_123",
    "name": "Support Assistant"
  },
  "currentVersion": {
    "id": "ver_1000",
    "versionNumber": 1,
    "parentVersionId": "ver_456",
    "forkType": "prompt_mutation"
  }
}

Get Agent Lineage

GET /api/agents/:id/lineage

Response:
{
  "root": {
    "id": "agent_123",
    "name": "Support Assistant",
    "versionId": "ver_456",
    "versionNumber": 5,
    "children": [
      {
        "id": "agent_999",
        "name": "Support Assistant (Spanish)",
        "forkType": "prompt_mutation",
        "children": []
      }
    ]
  }
}

Versions

Every agent has version history. Create new versions, compare them, and roll back when needed.

List Versions

GET /api/agents/:id/versions?page=1&limit=20

Response:
{
  "data": [
    {
      "id": "ver_456",
      "versionNumber": 5,
      "prompt": "...",
      "commitMessage": "Improved response quality",
      "createdAt": "2026-02-01T14:30:00Z",
      "createdBy": {
        "id": "user_123",
        "email": "you@example.com"
      }
    }
  ]
}

Create New Version

POST /api/agents/:id/versions
Content-Type: application/json

{
  "prompt": "Updated prompt with improvements...",
  "config": {
    "temperature": 0.5,
    "maxTokens": 3000
  },
  "commitMessage": "Reduced temperature for consistency"
}

Response:
{
  "id": "ver_457",
  "versionNumber": 6,
  "parentVersionId": "ver_456",
  "diffFromParent": {
    "config": {
      "changed": {
        "temperature": { "from": 0.7, "to": 0.5 },
        "maxTokens": { "from": 2000, "to": 3000 }
      }
    }
  }
}

Compare Versions

GET /api/agents/:id/versions/compare?from=ver_456&to=ver_457

Response:
{
  "from": { "id": "ver_456", "versionNumber": 5 },
  "to": { "id": "ver_457", "versionNumber": 6 },
  "diff": {
    "config": {
      "changed": {
        "temperature": { "from": 0.7, "to": 0.5 }
      }
    }
  }
}

Rollback to Version

POST /api/agents/:id/rollback
Content-Type: application/json

{
  "versionId": "ver_455"
}

Response:
{
  "id": "ver_458",
  "versionNumber": 7,
  "commitMessage": "Rollback to version 5"
}

Tasks

Tasks represent work to be executed by agents. Route tasks to specific agent versions and monitor their execution.

Create Task

POST /api/tasks
Content-Type: application/json

{
  "agentId": "agent_123",
  "versionId": "ver_456",  // Optional, uses current version if not specified
  "title": "Review PR #42",
  "description": "Review the authentication changes",
  "priority": "high",
  "input": {
    "pr_number": 42,
    "repository": "myorg/myrepo"
  }
}

Response:
{
  "id": "task_789",
  "agentId": "agent_123",
  "versionId": "ver_456",
  "title": "Review PR #42",
  "status": "queued",
  "priority": "high",
  "createdAt": "2026-02-02T10:00:00Z"
}

List Tasks

GET /api/tasks?status=running&agentId=agent_123

Response:
{
  "data": [
    {
      "id": "task_789",
      "title": "Review PR #42",
      "status": "running",
      "startedAt": "2026-02-02T10:00:30Z",
      "agent": {
        "id": "agent_123",
        "name": "Code Review Agent"
      }
    }
  ]
}

Get Task Details

GET /api/tasks/:id

Response:
{
  "id": "task_789",
  "title": "Review PR #42",
  "status": "completed",
  "priority": "high",
  "input": {
    "pr_number": 42,
    "repository": "myorg/myrepo"
  },
  "output": {
    "review": "Looks good, approved",
    "suggestions": [...]
  },
  "startedAt": "2026-02-02T10:00:30Z",
  "completedAt": "2026-02-02T10:02:15Z"
}

Update Task

PATCH /api/tasks/:id
Content-Type: application/json

{
  "status": "running",
  "output": {
    "partial_result": "Processing..."
  }
}

Webhooks

Receive real-time notifications when events occur in your account.

Create Webhook

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/Clawmit",
  "events": [
    "task.started",
    "task.completed",
    "task.failed",
    "agent.forked"
  ]
}

Response:
{
  "id": "hook_123",
  "url": "https://your-app.com/webhooks/Clawmit",
  "events": ["task.started", "task.completed", "task.failed", "agent.forked"],
  "secret": "whsec_abc123...",
  "active": true
}

Webhook Events

Available webhook events:

agent.created - New agent created
agent.updated - Agent modified
agent.forked - Agent forked
version.created - New version created
task.created - New task created
task.started - Task started execution
task.completed - Task completed successfully
task.failed - Task failed

Webhook Payload

POST https://your-app.com/webhooks/Clawmit
Content-Type: application/json
X-Clawmit-Signature: sha256=abc123...

{
  "event": "task.completed",
  "timestamp": "2026-02-02T10:02:15Z",
  "data": {
    "id": "task_789",
    "agentId": "agent_123",
    "status": "completed",
    "output": {...}
  }
}

Verify Webhook Signature

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

API Keys

Manage API keys for programmatic access with granular permission scopes.

Available Scopes

agents:read - Read agent data
agents:write - Create and modify agents
tasks:read - Read task data
tasks:write - Create and modify tasks
webhooks:read - Read webhook configurations
webhooks:write - Manage webhooks

List API Keys

GET /api/api-keys

Response:
{
  "data": [
    {
      "id": "key_123",
      "keyPrefix": "fc_live_12",
      "name": "Production API Key",
      "scopes": ["agents:read", "tasks:read"],
      "lastUsedAt": "2026-02-02T09:30:00Z",
      "createdAt": "2026-01-20T10:00:00Z"
    }
  ]
}

Revoke API Key

DELETE /api/api-keys/:id

Response: 204 No Content

Error Handling

Clawmit uses standard HTTP status codes and returns detailed error information.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "prompt",
        "message": "Required field missing"
      }
    ],
    "requestId": "req_abc123"
  }
}

Common Error Codes

400 Bad Request

Invalid request parameters or body

401 Unauthorized

Missing or invalid authentication

403 Forbidden

Insufficient permissions for this resource

404 Not Found

Resource does not exist

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error, contact support if persistent

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Default Limits

• 100 requests per minute per API key
• 10,000 requests per day per account
• Higher limits available for enterprise plans

Rate Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707390000

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your applications.

Self-Hosting

Clawmit is open source and can be self-hosted for full control over your infrastructure.

Requirements

Node.js 18 or higher
PostgreSQL 14 or higher
Redis (optional, for caching)

Quick Setup

# Download the release archive or clone your private copy
# git clone <your-self-hosted-repo>
cd clawmit

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Set up database
npm run db:push
npm run db:seed

# Build and start
npm run build
npm start

Environment Variables

DATABASE_URL=postgresql://user:password@localhost:5432/Clawmit
DIRECT_URL=postgresql://user:password@localhost:5432/Clawmit

JWT_SECRET=your-super-secret-key-change-this
JWT_EXPIRES_IN=7d

NEXTAUTH_URL=https://your-domain.com
NEXTAUTH_SECRET=another-secret-key

Docker Deployment

# Using Docker Compose
docker-compose up -d

# Or build manually
docker build -t Clawmit .
docker run -p 3000:3000 \
  -e DATABASE_URL=... \
  -e JWT_SECRET=... \
  Clawmit

For detailed deployment guides, production best practices, and troubleshooting, visit our full documentation.

Need Help?

If you have questions or need support:

Contact Support