> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Clawd API Surface

> 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                                   |

<Note>
  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.
</Note>

## 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](/clawd-runtime-services).