AgentSteadAPI Reference
Dashboard

AgentStead Public API v1

Programmatically create accounts, manage agents, connect channels, and send messages. Designed for autonomous AI agents and OpenClaw instances to self-serve.

Base URL: https://agentstead.com/api/v1

Authentication

Most endpoints require an API key. Get one by registering or logging in. Include it in every request:

Authorization: Bearer as_live_abc123...

API keys are long-lived. Each login generates a new key (old keys remain valid). Store keys securely.

Rate Limits

• Authenticated: 60 requests/minute per API key

• Register: 3 requests/hour per IP

• Login: 10 requests/minute per IP

Exceeding limits returns 429 Too Many Requests.

Errors

All errors return JSON:

{ "error": "Human-readable error message" }

400 — Bad request

401 — Invalid or missing API key

404 — Resource not found

409 — Conflict (duplicate)

429 — Rate limit exceeded

500 — Server error

Auth

POST/auth/register

Create a new account and get an API key.

Request:

{
  "email": "[email protected]",
  "password": "SecurePass123",
  "name": "My Agent Account"
}

Response (201):

{
  "apiKey": "as_live_abc123...",
  "userId": "clxyz...",
  "email": "[email protected]"
}

curl:

curl -X POST https://agentstead.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"SecurePass123"}'
POST/auth/login

Authenticate and get a new API key.

Request:

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

Response:

{ "apiKey": "as_live_def456...", "userId": "clxyz...", "email": "[email protected]" }

Account

GET/accountAuth

Get current account info.

{ "id": "clxyz...", "email": "[email protected]", "plan": "STARTER", "createdAt": "2025-01-01T..." }

Agents

GET/agentsAuth

List all your agents.

{ "agents": [{ "id": "...", "name": "My Agent", "status": "STOPPED", ... }] }
POST/agentsAuth

Create a new agent.

{
  "name": "My Agent",
  "description": "A helpful assistant",
  "personality": "You are friendly and concise.",
  "aiPlan": "BYOK",
  "defaultModel": "anthropic/claude-sonnet-4-20250514",
  "apiKeys": { "ANTHROPIC": "sk-ant-..." }
}

Response (201):

{ "agent": { "id": "...", "name": "My Agent", "status": "STOPPED", ... } }
GET/agents/:idAuth

Get agent details including channels.

{ "agent": { "id": "...", "name": "...", "status": "RUNNING", "channels": [...] } }
PATCH/agents/:idAuth

Update agent settings.

{ "name": "New Name", "personality": "Be concise." }
DELETE/agents/:idAuth

Delete an agent. Stops it first if running.

Agent Lifecycle

POST/agents/:id/startAuth

Start an agent. Provisions an ECS task.

{ "status": "STARTING", "taskArn": "arn:aws:ecs:..." }
POST/agents/:id/stopAuth

Stop a running agent.

{ "status": "STOPPED" }

Channels

GET/agents/:id/channelsAuth

List channels for an agent.

{ "channels": [{ "id": "...", "type": "TELEGRAM", "name": "Telegram", "enabled": true }] }
POST/agents/:id/channelsAuth

Add a channel (Telegram, Discord, etc.).

{ "type": "TELEGRAM", "botToken": "123456:ABC...", "name": "My Bot" }
DELETE/agents/:id/channels?channelId=...Auth

Remove a channel by ID.

Chat

POST/agents/:id/chatAuth

Send a message to a running agent.

// Request
{ "message": "Hello, what can you do?" }

// Response
{ "response": "I can help with many things!", "usage": { "tokens": 150 } }

Python example:

import requests

API_KEY = "as_live_..."
AGENT_ID = "your-agent-id"

r = requests.post(
    f"https://agentstead.com/api/v1/agents/{AGENT_ID}/chat",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"message": "Hello!"}
)
print(r.json()["response"])

Billing

POST/billing/checkoutAuth

Create a checkout session for a plan upgrade.

{ "plan": "PRO", "aiPlan": "PRO_AI" }
// Response (placeholder):
{ "checkoutUrl": null, "message": "Stripe integration coming soon.", "sessionId": null }
GET/billing/statusAuth

Check current billing status.

{ "plan": "STARTER", "aiPlan": "BYOK", "status": "inactive", "expiresAt": null }

Full Example

Register, create an agent, add Telegram, start it, and chat — all via API:

# 1. Register
API_KEY=$(curl -s -X POST https://agentstead.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"MyPass123!"}' | jq -r '.apiKey')

# 2. Create agent
AGENT_ID=$(curl -s -X POST https://agentstead.com/api/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"MyBot","aiPlan":"BYOK","apiKeys":{"ANTHROPIC":"sk-ant-..."}}' | jq -r '.agent.id')

# 3. Add Telegram channel
curl -s -X POST https://agentstead.com/api/v1/agents/$AGENT_ID/channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"TELEGRAM","botToken":"123:ABC..."}'

# 4. Start agent
curl -s -X POST https://agentstead.com/api/v1/agents/$AGENT_ID/start \
  -H "Authorization: Bearer $API_KEY"

# 5. Chat
curl -s -X POST https://agentstead.com/api/v1/agents/$AGENT_ID/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!"}'

💰 Crypto Payments (USDC)

Pay for AgentStead subscriptions with USDC — perfect for autonomous agents that need to pay without human intervention. Generate a unique deposit address, send the exact USDC amount, and your subscription activates automatically.

How It Works

  1. Call POST /billing/crypto/create-invoice with your desired plan
  2. Send the exact USDC amount to the returned deposit address
  3. Payment is auto-confirmed within ~2 minutes and your subscription activates

Supported chains: Base (recommended, low fees) and Polygon. USDC only. Invoices expire after 24 hours.

Create Invoice

POST /v1/billing/crypto/create-invoice
Authorization: Bearer as_live_...
Content-Type: application/json

{
  "plan": "PRO",
  "aiPlan": "PRO_AI",
  "months": 1,
  "chain": "base"
}

# Response:
{
  "data": {
    "invoiceId": "uuid",
    "amount": 39,
    "currency": "USDC",
    "chain": "base",
    "depositAddress": "0x...",
    "expiresAt": "2025-01-02T00:00:00Z",
    "status": "pending"
  }
}

Check Invoice Status

GET /v1/billing/crypto/invoice/:id
Authorization: Bearer as_live_...

# Automatically checks on-chain balance if pending

List Invoices

GET /v1/billing/crypto/invoices
Authorization: Bearer as_live_...

⚠️ Important: Send the exact USDC amount shown in the invoice. The deposit address is unique per invoice. Do not reuse addresses. Plans: Starter (1,380 ASTD), Pro (1,760 ASTD), Max (3,520 ASTD), Business (7,030 ASTD).