API Reference

GET /api/bots

curl https://api.aerostack.dev/api/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "bots": [
    {
      "id": "bt_a1b2c3d4e5f6g7h8i9j0",
      "name": "Support Bot",
      "slug": "support-bot",
      "platform": "telegram",
      "status": "active",
      "llm_provider": "anthropic",
      "llm_model": "claude-sonnet-4-6",
      "created_at": "2026-03-14T10:00:00Z",
      "updated_at": "2026-03-14T12:00:00Z",
      "last_active_at": "2026-03-14T15:30:00Z",
      "conversation_count": 42
    }
  ]
}

POST /api/bots

curl -X POST https://api.aerostack.dev/api/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Bot",
    "platform": "telegram",
    "workspace_id": "ws-abc123",
    "system_prompt": "You are a helpful assistant.",
    "platform_config": { "bot_token": "123:ABC" },
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini"
  }'

{
  "bot": {
    "id": "bt_a1b2c3d4e5f6g7h8i9j0",
    "name": "My Bot",
    "platform": "telegram",
    "status": "draft",
    "has_platform_config": true,
    "has_llm_api_key": false
  }
}

GET /api/bots/:id

curl https://api.aerostack.dev/api/bots/bt_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PATCH /api/bots/:id

curl -X PATCH https://api.aerostack.dev/api/bots/bt_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "Updated prompt.",
    "max_loop_iterations": 5,
    "spending_cap_cents": 1000
  }'

DELETE /api/bots/:id

curl -X DELETE https://api.aerostack.dev/api/bots/bt_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{ "deleted": true }

POST /api/bots/:id/activate

curl -X POST https://api.aerostack.dev/api/bots/bt_abc123/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "status": "active",
  "webhook_url": "https://api.aerostack.dev/api/bots/webhook/telegram/bt_abc123",
  "warnings": [],
  "manual_setup_required": false
}

POST /api/bots/:id/pause

curl -X POST https://api.aerostack.dev/api/bots/bt_abc123/pause \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{ "status": "paused" }

POST /api/bots/:id/test

curl -X POST https://api.aerostack.dev/api/bots/bt_abc123/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What can you help with?" }'

{
  "response": "I can help you with...",
  "tool_calls": [],
  "tokens": { "input": 342, "output": 28 },
  "token_breakdown": { "systemPrompt": 120, "total": 370 },
  "cost_cents": 0,
  "latency_ms": 1230,
  "loop_iterations": 0,
  "conversation_id": "bconv_abc123"
}

GET /api/bots/:id/conversations

curl "https://api.aerostack.dev/api/bots/bt_abc123/conversations?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/bots/:id/conversations/:convId

curl "https://api.aerostack.dev/api/bots/bt_abc123/conversations/bconv_xyz/messages?limit=200" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "conversation": {
    "id": "bconv_xyz",
    "platform_user_id": "user_123",
    "message_count": 15,
    "total_cost_cents": 3,
    "started_at": "2026-03-14T10:00:00Z",
    "last_message_at": "2026-03-14T10:05:00Z"
  },
  "messages": [
    { "id": "bmsg_1", "role": "user", "content": "Hello", "created_at": "..." },
    { "id": "bmsg_2", "role": "assistant", "content": "Hi there!", "created_at": "..." }
  ]
}

GET /api/bots/:id/analytics

curl "https://api.aerostack.dev/api/bots/bt_abc123/analytics?from=2026-03-01&to=2026-03-15" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/bots/:id/insights

curl https://api.aerostack.dev/api/bots/bt_abc123/insights \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "unanswered_questions": [
    { "question": "Can I get a refund?", "bot_response": "...", "created_at": "..." }
  ],
  "resolution_rate": 78,
  "total_answered": 312,
  "total_responses": 400
}

POST /api/bots/setup

curl -X POST https://api.aerostack.dev/api/bots/setup \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_support",
    "bot_name": "Acme Support",
    "platform": "telegram",
    "platform_config": { "bot_token": "123:ABC" },
    "config_values": { "company_name": "Acme Corp" }
  }'

GET /api/bots/templates

GET /api/bots/templates/:templateId

POST /api/bots/templates

PATCH /api/bots/templates/:templateId

DELETE /api/bots/templates/:templateId

curl -X POST https://api.aerostack.dev/api/bots/webhook/custom/bt_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello",
    "user_id": "user_1",
    "channel_id": "channel_1",
    "user_name": "Jane"
  }'

{
  "response": "Hi Jane! How can I help?",
  "tool_calls": [],
  "tokens": { "input": 200, "output": 15 },
  "cost_cents": 0,
  "latency_ms": 890
}

{ "error": "Error description" }