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:

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 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:

curl -X GET https://backend.example.com/api/openclaw/instances \
  -H "Authorization: Bearer YOUR_INTERNAL_API_KEY"

See the auth API 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 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.

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

{
  "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

{
  "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 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 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:

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();