> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference
> Complete API reference for Agentbot
# API reference
Complete API reference for Agentbot.
## Base URL
```
https://agentbot.raveculture.xyz/api
```
## Authentication
Agentbot supports multiple 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:
```bash theme={null}
curl -X GET https://agentbot.raveculture.xyz/api/agents \
-H "Authorization: Bearer YOUR_API_KEY"
```
API keys use the `sk_` prefix and are shown only once at creation time. See the [keys API](/api-reference/keys) for details.
### API key authentication (backend)
Backend endpoints such as `/api/deployments` and `/api/openclaw/instances` use a shared internal API key for authentication. Include the key as a bearer token:
```bash theme={null}
curl -X GET https://backend.example.com/api/openclaw/instances \
-H "Authorization: Bearer YOUR_INTERNAL_API_KEY"
```
See the [auth API](/api-reference/auth#api-key-authentication-backend-core-endpoints) for details.
## Data isolation
All authenticated API requests are scoped to the calling user's data through row-level security (RLS) policies at the database level. You can only read and modify resources that belong to your account. See [Security](/security#row-level-security) for the full list of protected tables and how isolation works.
## Rate limits
The backend API enforces per-IP rate limits using standard `RateLimit-*` response headers. When a limit is exceeded, the API returns `429 Too Many Requests`.
### Backend API rate limits
| Scope | Applies to | Limit | Error message |
| ------------------ | ----------------------- | ------------------ | -------------------------------------- |
| General | All `/api/*` routes | 120 req/min per IP | `Too many requests, please slow down.` |
| AI (all endpoints) | `/api/ai/*` routes | 30 req/min per IP | `AI rate limit exceeded.` |
| Deployments | `POST /api/deployments` | 5 req/min per IP | `Deployment rate limit exceeded.` |
### Web API rate limits
| Endpoint | Limit |
| --------------------------- | ------------------- |
| `/api/v1/gateway` | 100/min |
| `/api/agents` | 100/min |
| `/api/chat` | 60/min |
| `/api/instance/*` | 30/min |
| `/api/provision` | 5/min |
| `/api/register` | Rate-limited per IP |
| `/api/auth/forgot-password` | Rate-limited per IP |
| `/api/auth/reset-password` | Rate-limited per IP |
### Rate limit response headers
All rate-limited responses include standard headers:
| Header | Description |
| --------------------- | -------------------------------------------------- |
| `RateLimit-Limit` | Maximum requests allowed in the current window |
| `RateLimit-Remaining` | Requests remaining in the current window |
| `RateLimit-Reset` | Time in seconds until the rate limit window resets |
Legacy `X-RateLimit-*` headers are not sent. Use the unprefixed `RateLimit-*` headers instead.
## Request format
All POST and PUT requests that include a JSON body must set the `Content-Type` header to `application/json`. The backend API uses the Express JSON body parser, and requests without this header may result in an empty or undefined request body.
Request bodies are limited to **1 MB**. Requests exceeding this limit are rejected before reaching the endpoint handler.
```bash theme={null}
curl -X POST https://agentbot.raveculture.xyz/api/ai/chat \
-H "Content-Type: application/json" \
-H "x-user-plan: solo" \
-H "x-stripe-subscription-id: sub_123" \
-d '{"messages": [{"role": "user", "content": "Hello"}]}'
```
## Response format
### Success
```json theme={null}
{
"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
```json theme={null}
{
"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 — a paid subscription is mandatory for all agent provisioning and usage. The minimum plan is `solo`. Also returned when an [MPP](/payments/mpp) credential is missing for gateway requests. Requests using the deprecated `free` plan value receive this status. |
| 403 | Forbidden (insufficient permissions, token gating failure, bot detection, or missing CSRF token) |
| 404 | Resource not found |
| 429 | Too many requests or tier limit reached |
| 500 | Internal server error |
| 502 | Backend service unavailable |
| 503 | Service unavailable (for example, provisioning kill switch is active) |
## Endpoint reference
| Endpoint | Method | Description |
| ------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/api/v1/gateway` | POST | Route requests to plugins with Stripe or [MPP](/payments/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/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/agents/:id/start` | POST | Start an agent |
| `/api/agents/:id/stop` | POST | Stop an agent |
| `/api/agents/:id/restart` | POST | Restart an agent |
| `/api/agents/:id/update` | POST | Update agent image |
| `/api/agents/:id/repair` | POST | Repair an agent |
| `/api/agents/:id/reset-memory` | POST | Reset agent memory |
| `/api/agents/:id/token` | GET | Get agent gateway token |
| `/api/instance/:userId` | GET | Get instance details (web proxy) |
| `/api/instance/:userId/stats` | GET | Get instance stats (web proxy) |
| `/api/agents/clone` | POST | Clone an existing agent (requires x402 payment proof) |
| `/api/agents/clone` | GET | Clone service health check |
| `/api/agents/provision` | POST | Provision a new agent (web) |
| `/api/agents/provision` | GET | List provisioned agents (web) |
| `/api/agents/:id/verification` | GET | Get verification status (backend) |
| `/api/chat` | GET | List message history |
| `/api/chat` | POST | Send message to agent |
| `/api/demo/chat` | GET | List available demo models (no auth) |
| `/api/demo/chat` | POST | Send a demo chat message (no auth, rate-limited by IP) |
| `/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/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/keys/validate` | POST | Validate an API key (no session required) |
| `/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/wallet/top-up` | GET | Create a Stripe checkout session for wallet top-up |
| `/api/wallet/top-up` | POST | Stripe webhook for wallet top-up payment completion |
| `/api/provision` | POST | Provision agent with channel tokens (requires auth) |
| `/api/validate-key` | POST | Validate an API key (backend only) |
| `/api/register-home` | POST | Register a Home mode installation (backend only, requires identity headers) |
| `/api/register-link` | POST | Register a Link mode installation (backend only, requires identity headers) |
| `/api/installations` | GET | List registered installations (backend only, requires identity headers) |
| `/api/agent` | GET | Agent interaction (health, sessions, memory, skills, credentials) |
| `/api/agent` | POST | Agent interaction (chat, create-session, update-skill, set-credential) |
| `/api/files` | GET | List files for an agent |
| `/api/files` | POST | Upload a file for an agent |
| `/api/files` | DELETE | Delete a file |
| `/api/settings` | GET | Get current user profile |
| `/api/settings` | POST, PATCH | Update user profile |
| `/api/settings/password` | POST | Change password |
| `/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/security/risc` | GET | Cross-Account Protection endpoint health check |
| `/api/security/risc` | POST | Receive Google Cross-Account Protection (RISC) security events |
| `/api/auth/farcaster/verify` | GET, POST | Verify Farcaster identity (GET returns endpoint metadata) |
| `/api/auth/farcaster/refresh` | GET, POST | Refresh Farcaster token (GET returns endpoint metadata) |
| `/api/auth/token-gating/verify` | GET, POST | Verify token gating access |
| `/api/dashboard/cost` | GET | Get aggregated cost dashboard data (by agent, model, and day) |
| `/api/billing` | GET | Get billing info |
| `/api/billing` | POST | Billing actions (`create-checkout`, `enable-byok`, `disable-byok`, `get-usage`, `buy-credits`) |
| `/api/subscriptions/deploy` | POST | Activate a subscription tier for deployment (backend only, requires auth) |
| `/api/scheduled-tasks` | GET | List scheduled tasks (filtered by optional `agentId`) |
| `/api/scheduled-tasks` | POST | Create a scheduled task |
| `/api/scheduled-tasks` | PUT | Update a scheduled task |
| `/api/scheduled-tasks` | DELETE | Delete a scheduled task |
| `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`). Prices are in GBP. |
| `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) |
| `/api/stripe/storage-upgrade` | POST | Upgrade storage plan |
| `/api/metrics/:userId/historical` | GET | Get historical time-series metrics (backend only) |
| `/api/metrics/:userId/performance` | GET | Get current performance metrics (backend only) |
| `/api/metrics/:userId/summary` | GET | Get music industry metrics summary (backend only) |
| `/api/ai/health` | GET | AI provider availability (backend only) |
| `/api/ai/models` | GET | List available AI models (backend only) |
| `/api/ai/models/:provider` | GET | List models for a provider (backend only) |
| `/api/ai/models/select` | POST | Smart model selection for a task type (backend only) |
| `/api/ai/chat` | POST | Universal chat completion (backend only, requires subscription plan) |
| `/api/ai/estimate-cost` | POST | Estimate token cost (backend only) |
| `/api/render-mcp/health` | GET | Render MCP gateway health check (backend only) |
| `/api/render-mcp/info` | GET | Render MCP server metadata (backend only) |
| `/api/render-mcp/setup` | GET | Render MCP setup instructions (backend only) |
| `/api/render-mcp/tools` | GET | List Render MCP tools (backend only) |
| `/api/render-mcp/examples` | GET | Example Render MCP prompts (backend only) |
| `/api/render-mcp/validate-config` | POST | Validate Render API key (backend only) |
| `/api/render-mcp/docs` | GET | Redirect to Render MCP docs (backend only) |
| `/api/render-mcp/github` | GET | Redirect to Render MCP GitHub repo (backend only) |
| `/api/openclaw/version` | GET | Get OpenClaw runtime version (backend only) |
| `/api/openclaw/instances` | GET | List running agent instances (backend only, requires auth) |
| `/api/openclaw/instances/:id/stats` | GET | Get instance container stats (backend only, requires auth) |
| `/api/deployments` | POST | Deploy an agent container (backend only, requires auth) |
| `/api/models` | GET | List available OpenRouter AI models |
| `/api/basefm/live` | GET | List active Mux live streams |
| `/api/basefm/streams` | POST | Create a Mux live stream (RAVE token-gated) |
| `/api/generate-video` | POST | Generate and upload a video (requires session) |
| `/api/webhooks/mux` | POST | Mux webhook receiver (signature-verified) |
| `/api/webhooks/resend` | POST | Resend email webhook — inbound email processing and outbound event tracking (sent, delivered, bounced, opened, clicked, complained) |
| `/api/mission-control/fleet/graph` | GET | Get agent fleet constellation graph |
| `/api/mission-control/fleet/traces` | GET | Get real-time execution traces |
| `/api/mission-control/fleet/costs` | GET | Get per-agent cost attribution |
| `/api/mission-control/fleet/bookings` | GET | Get talent bookings |
| `/api/logs/:agentId/stream` | GET | Stream live agent logs via SSE (backend only) |
| `/api/logs/:agentId/history` | GET | Get buffered log lines (backend only) |
| `/api/logs/:agentId/stop` | POST | Stop a live log stream (backend only) |
| `/api/logs/active` | GET | List active log streams (backend only) |
| `/api/browse/tree` | GET | Get workspace file tree (backend only, requires auth) |
| `/api/browse/read` | GET | Read a workspace file (backend only, requires auth) |
| `/api/browse/write` | POST | Write a workspace file (backend only, requires auth) |
| `/api/browse/git-status` | GET | Get workspace git status (backend only, requires auth) |
| `/api/browse/git-diff` | GET | Get workspace git diff (backend only, requires auth) |
| `/api/browse/git-sync` | POST | Commit and push workspace changes (backend only, requires auth) |
| `/api/browse/git-log` | GET | Get workspace commit history (backend only, requires auth) |
| `/api/usage/summary` | GET | Get aggregated token usage summary (backend only, requires auth) |
| `/api/usage/by-agent/:agentId` | GET | Get token usage for a specific agent (backend only, requires auth) |
| `/api/usage/by-model` | GET | Get token usage grouped by model (backend only, requires auth) |
| `/api/usage/daily` | GET | Get daily token usage totals (backend only, requires auth) |
| `/api/usage/tools` | GET | Get tool execution statistics (backend only, requires auth) |
| `/api/swarms` | GET | List agent swarms |
| `/api/swarms` | POST | Create an agent swarm |
| `/api/underground/bus/send` | POST | Send an agent-to-agent message (signature-verified) |
| `/api/underground/events` | GET | List underground events (backend only, requires auth) |
| `/api/underground/events` | POST | Create an underground event (backend only, requires auth) |
| `/api/underground/wallets` | POST | Create an agent wallet (backend only, requires auth) |
| `/api/underground/wallets/:address/balance` | GET | Get agent wallet USDC balance (backend only, requires auth) |
| `/api/underground/splits` | POST | Create and queue a royalty split (backend only, requires auth) |
| `/api/colony/status` | GET | Get colony tree, soul cognitive state, or diagnostics |
| `/api/invite/generate` | POST | Generate an invite code (backend only, requires internal API key) |
| `/api/invite/validate` | POST | Validate and consume an invite code (backend only, no auth) |
| `/api/summarize` | POST | Summarize a URL — returns title, description, headings, paragraphs, word count (web summarizer service) |
| `/api/extract` | POST | Extract links, images, and Open Graph metadata from a URL (web summarizer service) |
| `/api/clawmerchants` | GET | List available ClawMerchants data feeds, or fetch a specific feed by `feed` query parameter |
## SDK
Use the Agentbot SDK:
```bash theme={null}
npm install @agentbot/sdk
```
```typescript theme={null}
import { Agentbot } from '@agentbot/sdk';
const client = new Agentbot({
apiKey: process.env.AGENTBOT_API_KEY
});
const agents = await client.agents.list();
```