API Documentation

Complete reference for the SudoClaw API. All endpoints require authentication unless noted.

Base URL

https://sudoclaw-api.aitoehigie.workers.dev

Authentication

Include your session token in the Authorization header:

Authorization: Bearer <session_token>

Authentication

POST/api/auth/register

Register a new user

Request Body:

{
  "email": "[email protected]",
  "password": "securepassword",
  "name": "John Doe"
}

Response:

{
  "success": true,
  "data": {
    "userId": "user_xxx",
    "email": "[email protected]",
    "sessionToken": "jwt_token"
  }
}
POST/api/auth/login

Login and get session token

Request Body:

{
  "email": "[email protected]",
  "password": "securepassword"
}

Response:

{
  "success": true,
  "data": {
    "userId": "user_xxx",
    "email": "[email protected]",
    "sessionToken": "jwt_token"
  }
}
POST/api/auth/logout

Logout and invalidate session

Response:

{
  "success": true,
  "message": "Logged out successfully"
}
GET/api/auth/me

Get current user info

Response:

{
  "success": true,
  "data": {
    "id": "user_xxx",
    "email": "[email protected]",
    "name": "John Doe",
    "organizations": []
  }
}

Organizations

GET/api/organizations

List user organizations

Response:

{
  "success": true,
  "data": {
    "organizations": []
  }
}
POST/api/organizations

Create new organization

Request Body:

{
  "name": "My Company",
  "slug": "my-company"
}

Response:

{
  "success": true,
  "data": {
    "organization": {
      "id": "org_xxx",
      "name": "My Company"
    }
  }
}
GET/api/organizations/:orgId

Get organization details

Response:

{
  "success": true,
  "data": {
    "organization": {
      "id": "org_xxx",
      "name": "My Company"
    }
  }
}
POST/api/organizations/:orgId/members

Invite member to organization

Request Body:

{
  "email": "[email protected]",
  "role": "member"
}

Response:

{
  "success": true,
  "message": "Member invited successfully"
}

Agents

GET/api/agents

List all agents

Response:

{
  "success": true,
  "data": {
    "agents": []
  }
}
POST/api/agents

Create new agent

Request Body:

{
  "name": "My Agent",
  "description": "A helpful assistant"
}

Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent_xxx",
      "name": "My Agent",
      "status": "deploying"
    }
  }
}
GET/api/agents/:agentId

Get agent details

Response:

{
  "success": true,
  "data": {
    "agent": {},
    "skills": [],
    "metrics": [],
    "alerts": []
  }
}
PATCH/api/agents/:agentId

Update agent

Request Body:

{
  "name": "Updated Name"
}

Response:

{
  "success": true,
  "data": {
    "agent": {}
  }
}
DELETE/api/agents/:agentId

Delete agent

Response:

{
  "success": true,
  "message": "Agent deleted successfully"
}
POST/api/agents/:agentId/skills

Add skill to agent

Request Body:

{
  "skillName": "web_search",
  "skillUrl": "https://..."
}

Response:

{
  "success": true,
  "data": {
    "skill": {}
  }
}
GET/api/agents/:agentId/health

Get agent health status

Response:

{
  "success": true,
  "data": {
    "status": "online",
    "last_seen": 1234567890
  }
}
POST/api/agents/:agentId/heartbeat

Agent heartbeat (internal)

Request Body:

{
  "status": "online",
  "metrics": {
    "api_calls": 100
  }
}

Response:

{
  "success": true,
  "message": "Heartbeat recorded"
}

Billing

GET/api/billing/plans

List pricing plans

Response:

{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "free",
        "name": "Free",
        "price": 0
      },
      {
        "id": "pro",
        "name": "Pro",
        "price": 29
      }
    ]
  }
}
POST/api/billing/create-checkout

Create checkout session

Request Body:

{
  "priceId": "price_xxx",
  "organizationId": "org_xxx"
}

Response:

{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.polar.sh/...",
    "checkoutId": "chk_xxx"
  }
}
GET/api/billing/usage/:orgId

Get usage for organization

Response:

{
  "success": true,
  "data": {
    "agents": 3,
    "apiCalls": 15000,
    "cost": 12.5
  }
}

Telegram

GET/api/telegram/webhook

Telegram webhook verification

Query Parameters:

{
  "hub_mode": "subscribe",
  "hub_verify_token": "..."
}

Response:

"challenge_string"
POST/api/telegram/webhook

Telegram webhook handler

Request Body:

{
  "update_id": 123,
  "message": {
    "chat": {
      "id": 12345
    },
    "text": "/start"
  }
}

Response:

{
  "ok": true
}
POST/api/telegram/send

Send message to Telegram user

Request Body:

{
  "chatId": "12345",
  "text": "Hello!",
  "agentId": "agent_xxx"
}

Response:

{
  "ok": true
}

Rate Limiting

API requests are rate limited based on your plan. Free plans: 100 requests/hour. Pro plans: 10,000 requests/hour.

Error Responses

All errors return a consistent format:

{
  "success": false,
  "error": "Error message"
}

Common status codes: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 429 (Rate Limited), 500 (Server Error).