Agents API

All agent endpoints require authentication. Agents are scoped to the authenticated user.

List Agents

GET /agents

Query parameters:

Parameter	Type	Default	Description
limit	integer	20	Items per page (1-100)
offset	integer	0	Items to skip
status	string	—	Filter by deployment status
sort	string	created_at	Sort field: created_at, name, updated_at
order	string	desc	Sort order: asc or desc

Response:

{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Agent",
      "system_prompt": "You are a helpful assistant.",
      "model": "qwen3-coder-next",
      "deployment_status": "running",
      "vm_url": "https://agent-abc123.example.com",
      "source": "liberclaw",
      "skills": ["web_search"],
      "has_telegram_bot": false,
      "owner_telegram_id": null,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:35:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

curl:

curl https://api.liberclaw.ai/api/v1/agents \
  -H "Authorization: Bearer <access_token>"

JavaScript:

const res = await fetch("https://api.liberclaw.ai/api/v1/agents", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { agents, total } = await res.json();

---

Create Agent

POST /agents

Creates a new agent and starts background deployment to an Aleph Cloud VM.

Request body:

Field	Type	Required	Description
name	string	Yes	Agent name (1-100 chars, alphanumeric + basic punctuation)
system_prompt	string	Conditional	System prompt (1-10000 chars). Required unless template_id is provided.
model	string	No	Model ID. Default: qwen3-coder-next
template_id	string	No	Use a predefined template for prompt, model, and skills
skills	string[]	No	List of skill IDs to enable
telegram_bot_token	string	No	Telegram bot token to attach
owner_telegram_id	string	No	Telegram user ID for the bot owner

{
  "name": "Research Assistant",
  "system_prompt": "You are a research assistant that helps find and summarize information.",
  "model": "qwen3-coder-next",
  "skills": ["web_search"]
}

Response: 201 Created with the Agent object.

The agent is created with deployment_status: "pending". Deployment happens in the background. Poll the deployment status endpoint to track progress.

curl:

curl -X POST https://api.liberclaw.ai/api/v1/agents \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "system_prompt": "You are a research assistant.",
    "model": "qwen3-coder-next"
  }'

Note

Agent creation is subject to per-tier limits. If you have reached your agent limit, the API returns 403 Forbidden.

---

Get Agent

GET /agents/{agent_id}

Response: Agent object

curl:

curl https://api.liberclaw.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <access_token>"

---

Update Agent

PATCH /agents/{agent_id}

Update one or more agent fields. Only provided fields are changed.

Request body:

Field	Type	Description
name	string	New name
system_prompt	string	New system prompt
model	string	New model ID
skills	string[]	New skill list
telegram_bot_token	string	Telegram bot token (empty string "" to remove)
owner_telegram_id	string	Telegram user ID (empty string "" to remove)

{
  "system_prompt": "You are a coding assistant specializing in Python.",
  "model": "glm-4.7"
}

Response: Updated Agent object.

Tip

After updating system_prompt, model, or skills, you should redeploy the agent for the changes to take effect on the running VM.

---

Delete Agent

DELETE /agents/{agent_id}

Deletes the agent and destroys its VM.

Response: 204 No Content

curl:

curl -X DELETE https://api.liberclaw.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <access_token>"

---

Bulk Delete

POST /agents/bulk-delete

Delete multiple agents in a single request (max 50).

Request body:

{
  "agent_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Response:

{
  "deleted": ["550e8400-e29b-41d4-a716-446655440000"],
  "not_found": ["660e8400-e29b-41d4-a716-446655440001"],
  "total_deleted": 1
}

---

Deployment Status

GET /agents/{agent_id}/status

Poll this endpoint during agent creation to track deployment progress.

Response:

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "deployment_status": "deploying",
  "vm_url": null,
  "steps": [
    { "key": "provision", "status": "done", "detail": "VM provisioned" },
    { "key": "deploy", "status": "active", "detail": "Uploading agent code..." },
    { "key": "health_check", "status": "pending", "detail": null }
  ],
  "logs": [
    { "timestamp": 1706000000.0, "level": "info", "message": "Starting deployment..." },
    { "timestamp": 1706000005.0, "level": "success", "message": "VM provisioned on CRN xyz" }
  ]
}

Deployment Status Values

Status	Description
pending	Agent created, deployment not yet started
deploying	Deployment in progress
running	Agent is live and responding
failed	Deployment failed

Deployment Status Stream (SSE)

GET /agents/{agent_id}/deploy/stream

Real-time SSE stream of deployment progress. Sends events as they happen instead of requiring polling.

Event types:

Type	Description
snapshot	Initial state with all current steps
log	A new log entry
step	A step status change
complete	Deployment finished (stream closes)

JavaScript:

const eventSource = new EventSource(
  `https://api.liberclaw.ai/api/v1/agents/${agentId}/deploy/stream`,
  // Note: EventSource doesn't support custom headers.
  // Use fetch with ReadableStream for auth (see Chat docs).
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  switch (data.type) {
    case "snapshot":
      console.log("Current steps:", data.steps);
      break;
    case "log":
      console.log(`[${data.level}] ${data.message}`);
      break;
    case "complete":
      console.log("Deployment finished:", data.deployment_status);
      eventSource.close();
      break;
  }
};

---

Agent Health

GET /agents/{agent_id}/health

Check if an agent’s VM is healthy and responding.

Response:

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "healthy": true,
  "vm_url": "https://agent-abc123.example.com",
  "agent_version": 3,
  "current_version": 3
}

When agent_version is less than current_version, a redeploy is recommended to update the agent code.

---

Rebuild Agent

POST /agents/{agent_id}/rebuild

Destroys the existing VM and deploys a fresh one from scratch. Use this when the VM is unresponsive or corrupted.

Only available when deployment_status is failed, pending, running, or deploying.

Response: Agent object with deployment_status: "pending".

---

Redeploy Agent

POST /agents/{agent_id}/redeploy

Pushes the latest code, configuration, and skills to the running VM without destroying it. This is an in-place update.

Only available when deployment_status is running or failed.

Response: Agent object with deployment_status: "deploying".

curl:

curl -X POST https://api.liberclaw.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/redeploy \
  -H "Authorization: Bearer <access_token>"

---

Export Agent

GET /agents/{agent_id}/export

Export an agent’s configuration as portable JSON for backup or sharing.

Response:

{
  "name": "Research Assistant",
  "system_prompt": "You are a research assistant.",
  "model": "qwen3-coder-next",
  "skills": ["web_search"],
  "export_version": 1
}

---

Import Agent

POST /agents/import

Create a new agent from an exported configuration. Starts deployment automatically.

Request body:

{
  "name": "Research Assistant",
  "system_prompt": "You are a research assistant.",
  "model": "qwen3-coder-next",
  "skills": ["web_search"],
  "export_version": 1
}

Response: 201 Created with the Agent object.

---

Agent API Keys

Agent API keys allow programmatic access to individual agents. The full key is only shown once at creation.

Create API Key

POST /agents/{agent_id}/api-keys

Request body:

{
  "label": "production"
}

Response: 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "label": "production",
  "key_prefix": "lc-abc123defg",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-01-15T10:30:00Z",
  "key": "lc-abc123defghijklmnopqrstuvwxyz..."
}

Caution

The key field is only returned at creation time. Store it securely — it cannot be retrieved again.

List API Keys

GET /agents/{agent_id}/api-keys

Returns all keys for the agent (prefix only, not the full key).

Response:

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "label": "production",
    "key_prefix": "lc-abc123defg",
    "is_active": true,
    "last_used_at": "2026-01-20T14:00:00Z",
    "created_at": "2026-01-15T10:30:00Z"
  }
]

Delete API Key

DELETE /agents/{agent_id}/api-keys/{key_id}

Response: 204 No Content

---

Agent Object

The standard agent response shape returned by most endpoints:

Field	Type	Description
id	UUID	Unique agent identifier
name	string	Agent display name
system_prompt	string	The agent’s system prompt
model	string	Model ID (e.g., qwen3-coder-next)
deployment_status	string	pending, deploying, running, or failed
vm_url	string or null	URL of the agent’s VM (set when running)
source	string	How the agent was created
skills	string[] or null	Enabled skill IDs
has_telegram_bot	boolean	Whether a Telegram bot is attached
owner_telegram_id	string or null	Telegram user ID for bot owner
created_at	datetime	ISO 8601 creation timestamp
updated_at	datetime	ISO 8601 last update timestamp