Skip to content

clawd-api-surface.mdx

Latest commit

 

History

History
70 lines (55 loc) · 3.84 KB

clawd-api-surface.mdx

File metadata and controls

70 lines (55 loc) · 3.84 KB
Raw
title Clawd API Surface
description Which APIs power clawd.rigbox.dev and how to reuse them in your own app

clawd.rigbox.dev is built on top of the same Rigbox API base (https://api.rigbox.dev/api/v1), plus Clawd-specific behavior for OpenClaw bots, AI credits, and billing UX.

Use this guide as an API map when building your own Clawd-like experience.

API Groups

Group What it does Should you use it in your own app?
Core Rigbox APIs Workspaces, apps, routing, logs, metrics, snapshots, tools Yes, these are the foundation
AI Config APIs AI provider settings, managed/BYOK state, credits, usage Yes, if you integrate AI providers
Clawd billing/plan APIs Checkout, plan switching, portal sessions Optional; use your own billing stack if preferred

Core Rigbox APIs Used by Clawd

Endpoint Used for
GET /workspaces, GET /workspaces/{id} Workspace list/detail state
POST /workspaces/{id}/start, POST /workspaces/{id}/stop Lifecycle controls
PUT /workspaces/{id}/resources Resize workspace RAM/vCPU/disk
GET /workspaces/{id}/metrics Runtime usage cards/graphs
GET /workspaces/{id}/logs Workspace-level logs
POST /quick-deploy One-shot template provisioning
POST /workspaces/{id}/reconcile-apps Ensure template apps exist
GET /apps, POST /apps, PATCH /apps/{id}, DELETE /apps/{id} App CRUD + rename
PUT /apps/{id}/visibility Public/private/privileged app access
GET /apps/{id}/health Live URL health validation
GET /apps/{id}/log-sources, GET /apps/{id}/logs, GET /apps/{id}/logs/stream App logs UI
GET /users/me/limits Plan limits and usage
GET /capacity Capacity checks before create flows
GET /api-keys, POST /api-keys, DELETE /api-keys/{id} Programmatic access management
GET /workspaces/{id}/tools, POST /workspaces/{id}/tools/{tool}/install Tool management
GET /setup-scripts, POST /setup-scripts Workspace initialization automation
GET /service-specs, POST /service-specs Service configuration templates

AI Config APIs Used by Clawd

These are the APIs that manage AI provider configuration:

Endpoint Responsibility
GET /workspaces/{id}/mode Read the workspace's effective AI mode
PUT /workspaces/{id}/mode Set the workspace AI mode (managed/BYOK)
GET /users/me/ai-defaults, PUT /users/me/ai-defaults Read/set the account default provider and model
POST /workspaces/{id}/env Provide a BYOK provider key as a workspace env var
GET /users/me/credits Managed AI credit balance
GET /users/me/ai-usage AI usage history
AI config is split: `PUT /workspaces/{id}/mode` sets a workspace's managed/BYOK mode, and `PUT /users/me/ai-defaults` sets the account-wide default provider and model. There is no combined per-workspace `ai-config` endpoint.

Billing and Subscriptions

Clawd handles billing through its own integration layer. If you build your own dashboard, use your preferred billing provider (Stripe, Paddle, etc.) - Rigbox's core workspace and AI APIs work independently of billing.

Minimal Clawd-Like Integration Flow

  1. Provision a workspace with POST /quick-deploy (template_id: "dev"), then install the OpenClaw bot gateway as an app recipe.
  2. Start and poll workspace state until running.
  3. Call POST /workspaces/{id}/reconcile-apps.
  4. Use GET /apps/{id}/health before surfacing app URLs as live.
  5. Set the workspace AI mode through PUT /workspaces/{id}/mode (and account-wide provider/model defaults via PUT /users/me/ai-defaults).
  6. Show plan/credit context with GET /users/me/limits and GET /users/me/credits.

For runtime internals (AI proxy and credit enforcement pipeline), continue to /clawd-runtime-services.