API reference

Complete API reference for Agentbot

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"

API keys use the 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

{
  "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/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	GET	List message history
/api/chat	POST	Send message to agent
/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/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/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/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/billing	GET	Get billing info
/api/billing	POST	Billing actions (create-checkout, enable-byok, disable-byok, get-usage, buy-credits)
/api/stripe/checkout	GET	Redirect to Stripe checkout (accepts plan query param: solo, collective, label, network)
/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)
/api/ai/estimate-cost	POST	Estimate token cost (backend only)

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