API reference
Complete API reference for Agentbot.
Base URL
https://agentbot.raveculture.xyz/api
Authentication
Agentbot supports two authentication methods depending on the endpoint.
Session authentication
Most web API endpoints use cookie-based session authentication via NextAuth. Sign in through the web application to obtain a session cookie.
API keys
You can generate API keys from the dashboard. Include your key in the Authorization header:
curl -X GET https://agentbot.raveculture.xyz/api/agents \
-H "Authorization: Bearer YOUR_API_KEY"
sk_ prefix and are shown only once at creation time. See the keys API for details.
Rate limits
| Endpoint | Limit |
|---|
/api/v1/gateway | 100/min |
/api/agents | 100/min |
/api/chat | 60/min |
/api/instance | 30/min |
/api/provision | Rate-limited per IP |
/api/register | Rate-limited per IP |
/api/auth/forgot-password | Rate-limited per IP |
/api/auth/reset-password | Rate-limited per IP |
Response format
Success
{
"success": true,
"data": {}
}
Some endpoints return domain-specific top-level keys (for example agents, keys, stats) instead of a generic data wrapper. Refer to each endpoint’s documentation for the exact response shape.
{
"error": "Description of the error"
}
HTTP status codes
| Code | Meaning |
|---|
| 200 | Success |
| 201 | Resource created |
| 400 | Bad request or validation error |
| 401 | Unauthorized (missing or invalid authentication) |
| 402 | Payment required (no active subscription or missing MPP credential) |
| 403 | Forbidden (insufficient permissions, token gating failure, or bot detection) |
| 404 | Resource not found |
| 429 | Too many requests or tier limit reached |
| 500 | Internal server error |
| 502 | Backend service unavailable |
| 503 | Service unavailable |
Endpoint reference
| Endpoint | Method | Description |
|---|
/api/v1/gateway | POST | Route requests to plugins with Stripe or MPP payment |
/api/agents | GET | List all agents |
/api/agents/:id | GET | Get agent details |
/api/agents/:id/config | GET | Get agent configuration |
/api/agents/:id/config | PUT | Update agent configuration |
/api/agents/:id/logs | GET | Get agent logs |
/api/agents/:id/messages | GET | Get agent messages |
/api/agents/:id/stats | GET | Get agent stats |
/api/agents/:id/verify | GET | Get verification status |
/api/agents/:id/verify | POST | Verify an agent |
/api/agents/:id/verify | DELETE | Remove verification |
/api/instance/:userId | GET | Get instance details |
/api/instance/:userId/start | POST | Start an agent |
/api/instance/:userId/stop | POST | Stop an agent |
/api/instance/:userId/restart | POST | Restart an agent |
/api/instance/:userId/update | POST | Update agent image |
/api/instance/:userId/repair | POST | Repair an agent |
/api/instance/:userId/reset-memory | POST | Reset agent memory |
/api/instance/:userId/token | GET | Get agent gateway token |
/api/instance/:userId/stats | GET | Get instance stats |
/api/agents/provision | POST | Provision a new agent |
/api/agents/provision | GET | List provisioned agents |
/api/chat | POST | Send message to agent |
/api/chat | GET | Get chat history |
/api/models | GET | List available AI models |
/api/health | GET | Health check |
/api/heartbeat | GET | Get heartbeat settings |
/api/heartbeat | POST | Update heartbeat settings |
/api/heartbeat | DELETE | Reset heartbeat settings |
/api/memory | GET | Get agent memory |
/api/memory | POST | Store agent memory |
/api/metrics | GET | Get platform-wide metrics |
/api/metrics/:userId/historical | GET | Get historical time-series metrics |
/api/metrics/:userId/performance | GET | Get current performance metrics |
/api/metrics/:userId/summary | GET | Get music industry metrics summary |
/api/credits | GET | Get credit balance |
/api/keys | GET | List API keys |
/api/keys | POST | Create API key |
/api/keys/:id | GET | Get API key details |
/api/keys/:id | DELETE | Delete API key |
/api/skills | GET | List skills marketplace |
/api/skills | POST | Install a skill on an agent |
/api/skills/:name | POST | Use a skill |
/api/skills/booking-settlement | GET, POST | Booking escrow and settlement |
/api/skills/instant-split | GET, POST | Royalty split execution |
/api/wallet | GET | Get wallet info |
/api/wallet | POST | Wallet actions (create, info) |
/api/wallet/address | GET | Get CDP wallet address |
/api/wallet/create | POST | Create a CDP wallet |
/api/wallet/cdp | GET | Get CDP wallet status |
/api/wallet/cdp | POST | Create a CDP wallet client |
/api/provision | POST | Provision agent with channel tokens |
/api/agent | GET | Agent interaction (health, sessions, memory, skills, credentials) |
/api/agent | POST | Agent interaction (chat, create-session, update-skill, set-credential) |
/api/register | POST | Create a new account |
/api/auth/callback/wallet | POST | Wallet sign in (SIWE) |
/api/auth/forgot-password | POST | Request password reset |
/api/auth/reset-password | POST | Reset password |
/api/auth/farcaster/verify | POST | Verify Farcaster identity |
/api/auth/farcaster/refresh | POST | Refresh Farcaster token |
/api/auth/token-gating/verify | GET, POST | Verify token gating access |
/api/billing | GET | Get billing info |
/api/billing | POST | Billing actions (checkout, BYOK, usage, credits) |
/api/stripe/checkout | GET | Start Stripe checkout |
/api/stripe/credits | GET | Purchase credit top-ups |
/api/stripe/storage-upgrade | POST | Upgrade storage plan |
/api/ai/health | GET | AI provider availability |
/api/ai/models | GET | List available AI models |
/api/ai/models/:provider | GET | List models for a provider |
/api/ai/models/select | POST | Smart model selection for a task type |
/api/ai/chat | POST | Universal chat completion |
/api/ai/estimate-cost | POST | Estimate token cost |
npm install @agentbot/sdk
import { Agentbot } from '@agentbot/sdk';
const client = new Agentbot({
apiKey: process.env.AGENTBOT_API_KEY
});
const agents = await client.agents.list();
