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.

JWT authentication (backend API)

Backend API endpoints use JWT bearer tokens for authentication. Include the token in the Authorization header:

curl -X GET https://agentbot.raveculture.xyz/api/instance/user_123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

The JWT payload contains userId, email, and role. Tokens expire after 7 days. See the auth API for token generation 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

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 — a paid subscription is mandatory for all agent provisioning and usage. 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

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`). 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)

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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

API reference

API reference

Base URL

Authentication

Session authentication

API keys

JWT authentication (backend API)

Data isolation

Rate limits

Response format

Success

Error

HTTP status codes

Endpoint reference

SDK

​API reference

​Base URL

​Authentication

​Session authentication

​API keys

​JWT authentication (backend API)

​Data isolation

​Rate limits

​Response format

​Success

​Error

​HTTP status codes

​Endpoint reference

​SDK

API reference

Base URL

Authentication

Session authentication

API keys

JWT authentication (backend API)

Data isolation

Rate limits

Response format

Success

Error

HTTP status codes

Endpoint reference

SDK