API Overview

The LiberClaw API provides programmatic access to create, deploy, and interact with AI agents on Aleph Cloud. All endpoints are RESTful JSON over HTTPS.

Base URL

https://api.liberclaw.ai/api/v1

All endpoints documented here are relative to this base URL. For example, GET /agents means GET https://api.liberclaw.ai/api/v1/agents.

Authentication

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Access tokens are short-lived JWTs (15 minutes). Use the refresh endpoint to obtain new tokens without re-authenticating. See the Authentication guide for all available login methods.

Error Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found",
    "status": 404,
    "details": null
  }
}

Field	Type	Description
code	string	Machine-readable error code (e.g., NOT_FOUND, UNAUTHORIZED, VALIDATION_ERROR)
message	string	Human-readable description
status	integer	HTTP status code
details	object or null	Additional context (validation errors include field-level details)

Error Codes

Code	HTTP Status	Description
BAD_REQUEST	400	Invalid request parameters
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions or quota exceeded
NOT_FOUND	404	Resource does not exist
CONFLICT	409	Resource conflict (e.g., duplicate email)
VALIDATION_ERROR	422	Request body failed validation
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Unexpected server error
BAD_GATEWAY	502	Agent VM unreachable

Validation Errors

When a request body fails validation, details contains an array of field-level errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 422,
    "details": [
      {
        "field": "body → name",
        "message": "String should have at least 1 character",
        "type": "string_too_short"
      }
    ]
  }
}

Rate Limiting

Rate limits are applied per IP address. When you exceed a limit, the API returns a 429 response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded: 5 per 1 minute",
    "status": 429,
    "details": null
  }
}

Key rate limits:

Endpoint	Limit
POST /auth/login/email	5/minute
POST /auth/verify-magic-link	10/minute
POST /auth/refresh	20/minute
POST /auth/wallet/*	10/minute
POST /auth/exchange	10/minute
POST /auth/guest	10/minute

Common Headers

Request Headers

Header	Required	Description
Authorization	Yes (most endpoints)	Bearer <access_token>
Content-Type	Yes (POST/PATCH)	application/json

Response Headers

Header	Description
Content-Type	application/json or text/event-stream for SSE endpoints

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
limit	integer	20	Items per page (1-100)
offset	integer	0	Number of items to skip

Paginated responses include total count:

{
  "agents": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Interactive Reference

For a complete interactive API explorer with all endpoints, see the Endpoint Reference.