Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Registration API

Register self-hosted (Home) and linked (Link) agent installations. These endpoints are backend-only and support the Home and Link deployment modes alongside the default Cloud mode.
Home mode runs the agent container on your own hardware via Docker. Link mode connects an existing OpenClaw instance to the Agentbot platform. Cloud mode (the default) runs the agent on Agentbot infrastructure.

​
Install script

GET /install
Returns the Home mode installation shell script. No authentication required. The response content type is text/plain. This script automates the setup of a self-hosted agent container. Pipe it to your shell to begin the Home mode installation: 
curl -sSL https://agentbot.sh/install | bash

GET /link
Returns the Link mode setup shell script. No authentication required. The response content type is text/plain. This script connects an existing OpenClaw instance to the Agentbot platform. Pipe it to your shell to begin the Link mode setup: 
curl -sSL https://agentbot.sh/link | bash

​
Validate API key

POST /api/validate-key
Validates a bearer token by computing a SHA-256 hash of the raw key and looking it up in the api_keys database table. Raw keys are never stored or compared directly. No session authentication is required — the API key is passed in the Authorization header.
The web application’s key validation endpoint uses a separate bcrypt-based lookup with the sk_ prefix convention. The backend endpoint documented here uses SHA-256 hashing and does not require the sk_ prefix.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token in the format Bearer YOUR_API_KEY

​
Response

{
  "valid": true,
  "userId": "user-a1b2c3d4",
  "plan": "solo",
  "features": ["dashboard", "marketplace", "analytics"]
}
FieldTypeDescription
validbooleanWhether the key is valid
userIdstringUser identifier
planstringCurrent subscription plan (label, solo, collective, or network)
featuresstring[]List of features available to the user

​
Errors

CodeDescription
401Missing bearer token or key is invalid
500Internal error during key validation

​
Register Home installation

POST /api/register-home
Registers a Home mode installation. Requires identity headers (x-user-email, x-user-id, x-user-role) set by the authenticated frontend. The backend middleware extracts these headers but does not independently verify a bearer token on this route.
The web proxy forwards identity headers from the active session. The backend authenticate middleware reads these headers and attaches them to the request context. If no headers are provided, userId defaults to anonymous.

​
Request body

FieldTypeRequiredDescription
userIdstringYesUser identifier
modestringNoDeployment mode (defaults to home)
gatewayTokenstringNoGateway token for the installation

​
Response

{
  "success": true,
  "message": "Home installation registered",
  "dashboardUrl": "https://agentbot.raveculture.xyz/dashboard"
}

​
Errors

CodeDescription
400userId is required
500Internal server error
POST /api/register-link
Registers a Link mode installation that connects an existing OpenClaw instance. Requires identity headers (x-user-email, x-user-id, x-user-role) set by the authenticated frontend.
The web proxy forwards identity headers from the active session. The backend authenticate middleware reads these headers and attaches them to the request context. If no headers are provided, userId defaults to anonymous.

​
Request body

FieldTypeRequiredDescription
userIdstringYesUser identifier
gatewayTokenstringNoGateway token for the linked instance

​
Response

{
  "success": true,
  "message": "OpenClaw instance linked",
  "dashboardUrl": "https://agentbot.raveculture.xyz/dashboard"
}

​
Errors

CodeDescription
400userId is required
500Internal server error

​
List installations

GET /api/installations
Returns registered installations belonging to the authenticated user. Results are scoped to the caller’s identity — you can only see your own installations. Requires identity headers (x-user-email, x-user-id, x-user-role) set by the authenticated frontend.
This endpoint filters results by the authenticated user’s ID. Each user can only view their own installations across all deployment modes.

​
Response

{
  "success": true,
  "count": 1,
  "installations": [
    {
      "user_id": "user-a1b2c3d4",
      "mode": "home",
      "registered_at": "2026-03-21T00:00:00Z",
      "last_seen": "2026-03-21T12:00:00Z",
      "status": "active"
    }
  ]
}
FieldTypeDescription
installations[].user_idstringUser identifier
installations[].modestringDeployment mode: home, link, or cloud
installations[].registered_atstringISO 8601 timestamp of registration
installations[].last_seenstringISO 8601 timestamp of last heartbeat
installations[].statusstringCurrent status: active or inactive

​
Errors

CodeDescription
500Internal server error

​
Get registration token (internal)

GET /api/registration/token
Returns the gateway token for a user from the agent registrations table. This is an internal API used by the Edge Runtime dashboard to retrieve gateway tokens without direct database access from edge functions.

​
Query parameters

ParameterTypeRequiredDescription
userIdstringYesUser identifier to look up the gateway token for

​
Response

{
  "gateway_token": "a1b2c3d4e5f6..."
}
FieldTypeDescription
gateway_tokenstring | nullThe gateway token associated with the user’s agent registration. null when no registration exists for the user.

​
Errors

CodeDescription
400userId required — the userId query parameter is missing
500Failed to fetch token
This endpoint queries the agent_registrations table directly. It does not require session authentication and is intended for internal service-to-service calls within the Edge Runtime.

​
Registration heartbeat

POST /api/heartbeat
Reports the status of a registered installation. When the userId matches a known registration, the last_seen timestamp is updated and the status is set to active. Requires authentication.
This is a backend registration heartbeat for Home and Link installations. It is separate from the web heartbeat settings endpoint, which configures heartbeat scheduling for the web dashboard.

​
Authentication

This endpoint uses the authenticate middleware which reads identity headers (x-user-email, x-user-id, x-user-role) from the request. If no headers are provided, the middleware assigns default values (userId defaults to anonymous) and the request proceeds. The middleware does not reject unauthenticated requests.

​
Request body

FieldTypeRequiredDescription
userIdstringNoUser identifier of the registered installation

​
Response

{
  "success": true,
  "timestamp": "2026-03-21T12:00:00Z"
}