Skip to main content

​
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

ScopeApplies toLimitError message
GeneralAll /api/* routes120 req/min per IPToo many requests, please slow down.
AI (all endpoints)/api/ai/* routes30 req/min per IPAI rate limit exceeded.
DeploymentsPOST /api/deployments5 req/min per IPDeployment rate limit exceeded.

​
Web API rate limits

EndpointLimit
/api/v1/gateway100/min
/api/agents100/min
/api/chat60/min
/api/instance/*30/min
/api/provision5/min
/api/registerRate-limited per IP
/api/auth/forgot-passwordRate-limited per IP
/api/auth/reset-passwordRate-limited per IP

​
Rate limit response headers

All rate-limited responses include standard headers:
HeaderDescription
RateLimit-LimitMaximum requests allowed in the current window
RateLimit-RemainingRequests remaining in the current window
RateLimit-ResetTime 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

CodeMeaning
200Success
201Resource created
400Bad request or validation error
401Unauthorized (missing or invalid authentication)
402Payment 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.
403Forbidden (insufficient permissions, token gating failure, bot detection, or missing CSRF token)
404Resource not found
429Too many requests or tier limit reached
500Internal server error
502Backend service unavailable
503Service unavailable (for example, provisioning kill switch is active)

​
Endpoint reference

EndpointMethodDescription
/api/v1/gatewayPOSTRoute requests to plugins with Stripe or MPP payment
/api/agentsGETList all agents
/api/agents/:idGETGet agent details
/api/agents/:id/configGETGet agent configuration
/api/agents/:id/configPUTUpdate agent configuration
/api/agents/:id/messagesGETGet agent messages
/api/agents/:id/statsGETGet agent stats
/api/agents/:id/verifyGETGet verification status
/api/agents/:id/verifyPOSTVerify an agent
/api/agents/:id/verifyDELETERemove verification
/api/agents/:id/startPOSTStart an agent
/api/agents/:id/stopPOSTStop an agent
/api/agents/:id/restartPOSTRestart an agent
/api/agents/:id/updatePOSTUpdate agent image
/api/agents/:id/repairPOSTRepair an agent
/api/agents/:id/reset-memoryPOSTReset agent memory
/api/agents/:id/tokenGETGet agent gateway token
/api/instance/:userIdGETGet instance details (web proxy)
/api/instance/:userId/statsGETGet instance stats (web proxy)
/api/agents/clonePOSTClone an existing agent (requires x402 payment proof)
/api/agents/cloneGETClone service health check
/api/agents/provisionPOSTProvision a new agent (web)
/api/agents/provisionGETList provisioned agents (web)
/api/agents/:id/verificationGETGet verification status (backend)
/api/chatGETList message history
/api/chatPOSTSend message to agent
/api/demo/chatGETList available demo models (no auth)
/api/demo/chatPOSTSend a demo chat message (no auth, rate-limited by IP)
/api/healthGETHealth check
/api/heartbeatGETGet heartbeat settings
/api/heartbeatPOSTUpdate heartbeat settings
/api/heartbeatDELETEReset heartbeat settings
/api/memoryGETGet agent memory
/api/memoryPOSTStore agent memory
/api/metricsGETGet platform-wide metrics
/api/creditsGETGet credit balance
/api/keysGETList API keys
/api/keysPOSTCreate API key
/api/keys/:idGETGet API key details
/api/keys/:idDELETEDelete API key
/api/keys/validatePOSTValidate an API key (no session required)
/api/skillsGETList skills marketplace
/api/skillsPOSTInstall a skill on an agent
/api/skills/:namePOSTUse a skill
/api/skills/booking-settlementGET, POSTBooking escrow and settlement
/api/skills/instant-splitGET, POSTRoyalty split execution
/api/walletGETGet wallet info
/api/walletPOSTWallet actions (create, info)
/api/wallet/addressGETGet CDP wallet address
/api/wallet/createPOSTCreate a CDP wallet
/api/wallet/cdpGETGet CDP wallet status
/api/wallet/cdpPOSTCreate a CDP wallet client
/api/provisionPOSTProvision agent with channel tokens (requires auth)
/api/validate-keyPOSTValidate an API key (backend only)
/api/register-homePOSTRegister a Home mode installation (backend only, requires identity headers)
/api/register-linkPOSTRegister a Link mode installation (backend only, requires identity headers)
/api/installationsGETList registered installations (backend only, requires identity headers)
/api/agentGETAgent interaction (health, sessions, memory, skills, credentials)
/api/agentPOSTAgent interaction (chat, create-session, update-skill, set-credential)
/api/settingsGETGet current user profile
/api/settingsPOST, PATCHUpdate user profile
/api/settings/passwordPOSTChange password
/api/registerPOSTCreate a new account
/api/auth/callback/walletPOSTWallet sign in (SIWE)
/api/auth/forgot-passwordPOSTRequest password reset
/api/auth/reset-passwordPOSTReset password
/api/security/riscGETCross-Account Protection endpoint health check
/api/security/riscPOSTReceive Google Cross-Account Protection (RISC) security events
/api/auth/farcaster/verifyGET, POSTVerify Farcaster identity (GET returns endpoint metadata)
/api/auth/farcaster/refreshGET, POSTRefresh Farcaster token (GET returns endpoint metadata)
/api/auth/token-gating/verifyGET, POSTVerify token gating access
/api/dashboard/costGETGet aggregated cost dashboard data (by agent, model, and day)
/api/billingGETGet billing info
/api/billingPOSTBilling actions (create-checkout, enable-byok, disable-byok, get-usage, buy-credits)
/api/subscriptions/deployPOSTActivate a subscription tier for deployment (backend only, requires auth)
/api/scheduled-tasksGETList scheduled tasks (filtered by optional agentId)
/api/scheduled-tasksPOSTCreate a scheduled task
/api/scheduled-tasksPUTUpdate a scheduled task
/api/scheduled-tasksDELETEDelete a scheduled task
/api/stripe/checkoutGETRedirect to Stripe checkout (accepts plan query param: solo, collective, label, network). Prices are in GBP.
/api/stripe/creditsGETRedirect to Stripe credit purchase (accepts price query param)
/api/stripe/storage-upgradePOSTUpgrade storage plan
/api/metrics/:userId/historicalGETGet historical time-series metrics (backend only)
/api/metrics/:userId/performanceGETGet current performance metrics (backend only)
/api/metrics/:userId/summaryGETGet music industry metrics summary (backend only)
/api/ai/healthGETAI provider availability (backend only)
/api/ai/modelsGETList available AI models (backend only)
/api/ai/models/:providerGETList models for a provider (backend only)
/api/ai/models/selectPOSTSmart model selection for a task type (backend only)
/api/ai/chatPOSTUniversal chat completion (backend only, requires subscription plan)
/api/ai/estimate-costPOSTEstimate token cost (backend only)
/api/render-mcp/healthGETRender MCP gateway health check (backend only)
/api/render-mcp/infoGETRender MCP server metadata (backend only)
/api/render-mcp/setupGETRender MCP setup instructions (backend only)
/api/render-mcp/toolsGETList Render MCP tools (backend only)
/api/render-mcp/examplesGETExample Render MCP prompts (backend only)
/api/render-mcp/validate-configPOSTValidate Render API key (backend only)
/api/render-mcp/docsGETRedirect to Render MCP docs (backend only)
/api/render-mcp/githubGETRedirect to Render MCP GitHub repo (backend only)
/api/openclaw/versionGETGet OpenClaw runtime version (backend only)
/api/openclaw/instancesGETList running agent instances (backend only, requires auth)
/api/openclaw/instances/:id/statsGETGet instance container stats (backend only, requires auth)
/api/deploymentsPOSTDeploy an agent container (backend only, requires auth)
/api/modelsGETList available OpenRouter AI models
/api/basefm/liveGETList active Mux live streams
/api/basefm/streamsPOSTCreate a Mux live stream (RAVE token-gated)
/api/generate-videoPOSTGenerate and upload a video (requires session)
/api/webhooks/muxPOSTMux webhook receiver (signature-verified)
/api/webhooks/resendPOSTResend inbound email webhook (signature-verified, sender allowlist)
/api/mission-control/fleet/graphGETGet agent fleet constellation graph
/api/mission-control/fleet/tracesGETGet real-time execution traces
/api/mission-control/fleet/costsGETGet per-agent cost attribution
/api/mission-control/fleet/bookingsGETGet talent bookings
/api/logs/:agentId/streamGETStream live agent logs via SSE (backend only)
/api/logs/:agentId/historyGETGet buffered log lines (backend only)
/api/logs/:agentId/stopPOSTStop a live log stream (backend only)
/api/logs/activeGETList active log streams (backend only)
/api/browse/treeGETGet workspace file tree (backend only, requires auth)
/api/browse/readGETRead a workspace file (backend only, requires auth)
/api/browse/writePOSTWrite a workspace file (backend only, requires auth)
/api/browse/git-statusGETGet workspace git status (backend only, requires auth)
/api/browse/git-diffGETGet workspace git diff (backend only, requires auth)
/api/browse/git-syncPOSTCommit and push workspace changes (backend only, requires auth)
/api/browse/git-logGETGet workspace commit history (backend only, requires auth)
/api/usage/summaryGETGet aggregated token usage summary (backend only, requires auth)
/api/usage/by-agent/:agentIdGETGet token usage for a specific agent (backend only, requires auth)
/api/usage/by-modelGETGet token usage grouped by model (backend only, requires auth)
/api/usage/dailyGETGet daily token usage totals (backend only, requires auth)
/api/usage/toolsGETGet tool execution statistics (backend only, requires auth)
/api/swarmsGETList agent swarms
/api/swarmsPOSTCreate an agent swarm
/api/underground/bus/sendPOSTSend an agent-to-agent message (signature-verified)
/api/underground/eventsGETList underground events (backend only, requires auth)
/api/underground/eventsPOSTCreate an underground event (backend only, requires auth)
/api/underground/walletsPOSTCreate an agent wallet (backend only, requires auth)
/api/underground/wallets/:address/balanceGETGet agent wallet USDC balance (backend only, requires auth)
/api/underground/splitsPOSTCreate and queue a royalty split (backend only, requires auth)
/api/colony/statusGETGet colony tree, soul cognitive state, or diagnostics
/api/invite/generatePOSTGenerate an invite code (backend only, requires internal API key)
/api/invite/validatePOSTValidate and consume an invite code (backend only, no auth)
/api/summarizePOSTSummarize a URL — returns title, description, headings, paragraphs, word count (web summarizer service)
/api/extractPOSTExtract links, images, and Open Graph metadata from a URL (web summarizer service)
/api/clawmerchantsGETList 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();