Skip to content

Customer API reference

The OpenClaw Hosted control plane exposes a Connect RPC API over HTTP. All customer-facing services are served from:

1
https://api.clusterclaw.ai

Protobuf definitions are canonical: proto/openclaw/v1/. Regenerate OpenAPI from the repository root with make proto-openapi → apps/backstage/catalog/openapi/openclaw-v1.swagger.json.

Internal RPCs

The OpenAPI bundle may list OrchestratorService, LeaseService, and other internal services. Those are not exposed on the public customer endpoint. This document covers subscriber-facing services only.

Transport

Connect protocol

Unless annotated for REST, calls use HTTP POST with JSON-encoded protobuf messages:

1
2
3
4
5
POST /openclaw.v1.DeploymentService/CreateDeployment
Host: api.clusterclaw.ai
Content-Type: application/json
Connect-Protocol-Version: 1
Authorization: Bearer cc_your_api_key

Path pattern: /{package}.{Service}/{Method}

Health checks

Endpoint Response
GET /healthz ok
GET / ok

Use these to verify API reachability from your network or monitoring.

Authentication

See Authentication. Summary:

  • Public: AccountService.Signup, CatalogService.GetLaunchCatalog
  • Authenticated: all other customer RPCs — Authorization: Bearer cc_*

MeteringService handlers are mounted without the API-key interceptor (used by internal emitters). Customers should use BillingService for usage queries and MeteringService.GetDeploymentUsage only when integrating with documented metering flows.

Error model

Connect maps errors to HTTP status codes and JSON bodies:

Code HTTP When
invalid_argument 400 Missing/invalid fields
unauthenticated 401 Missing or bad API key
permission_denied 403 Tier guard (free deploy, autopilot without enterprise)
not_found 404 Unknown deployment or account
already_exists 409 Duplicate signup name
failed_precondition 412 Wrong deployment state (SSO, integration not configured)
internal 500 Server error

Example error body (Connect JSON):

1
2
3
4
{
  "code": "permission_denied",
  "message": "upgrade required to deploy — see https://clusterclaw.ai/pricing"
}

Rate limiting

The public API does not document per-customer request rate limits today. Protect integrations with exponential backoff on internal and transient network errors.

Usage limits (token caps) are separate — see Billing → Usage limits.

AccountService

Manage customer identity.

RPC Auth Description
Signup Public Create account; returns customer + apiKey
GetAccount Required Read authenticated customer

Signup

Request

1
2
3
4
5
6
{
  "name": "acme",
  "tier": "developer",
  "plan": "developer",
  "email": "ops@acme.example"
}

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "customer": {
    "id": "…",
    "name": "acme",
    "tier": "developer",
    "plan": "developer",
    "status": "active"
  },
  "apiKey": "cc_…"
}

Valid tiers: free, starter, hobbyist, developer, team, business.

CatalogService

Read-only launch metadata for UI, CLI, and automation.

RPC Auth Description
GetLaunchCatalog Public Models, channels, guided field schemas

Response highlights

  • version — catalog schema version
  • models[] — id, label, provider
  • channels[] — id, label, tier, docsUrl, summary, setupMode, fields[]

Secrets are never returned.

DeploymentService

Full deployment lifecycle.

RPC Description
CreateDeployment Provision gateway
GetDeployment Read by ID
ListDeployments Paginated list
UpdateDeployment Resize, inference, hostname, image refresh
StopDeployment Stop runtime
StartDeployment Start runtime
RestartDeployment Restart pods/service
DeleteDeployment Tear down
GetDeploymentStatus Health + channels
GetDeploymentLogs Recent logs
GetDeploymentGatewayCredentials SSO URL + token (guarded)

CreateDeployment (selected fields)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "name": "prod",
  "region": "us-central1",
  "plan": "developer",
  "sizeClass": "small",
  "channelTier": "bot-first",
  "pvcSize": "20Gi",
  "inferenceMode": "INFERENCE_MODE_PLATFORM_MANAGED",
  "providerName": "openai",
  "targetClass": "cloud_run",
  "publicIngressEnabled": true,
  "publicHostname": "prod",
  "modelPrimary": "openai/gpt-5.4-mini",
  "autoUpdate": true,
  "autoUpdateChannel": "stable",
  "seedOverridesJson": "{}",
  "providerApiKey": "",
  "skills": []
}

providerApiKey is required when inferenceMode is INFERENCE_MODE_BYOK. It is written to secure storage and never returned.

Deployment status enum

DEPLOYMENT_STATUS_QUEUED, PROVISIONING, PROVISIONING_SERVICE, DNS_PENDING, TLS_PENDING, HEALTHY, DEGRADED, BACKUP_WARNING, SUSPENDED, DELETING, FAILED

UpdateDeployment

Notable fields: refreshRuntimeImage (bool) — re-provision Cloud Run to pick up latest platform digest without changing imageTag.

GetDeploymentGatewayCredentials

Returns:

1
2
3
4
{
  "gatewayToken": "ccgw_…",
  "gatewayUrl": "https://prod.clusterclaw.ai"
}

Fails with failed_precondition if public ingress disabled or status is not HEALTHY.

BillingService

Stripe subscriptions, usage summaries, rate cards, spending limits.

RPC Description
CreateCheckoutSession Start Stripe Checkout (tier, URLs)
CreateBillingPortalSession Manage subscription/invoices
GetSubscription Current plan/status
GetUsageSummary Line items for date range
GetCurrentCharges Current month estimate
GetRateCard Unit prices for tier
GetUsageLimits List token caps
SetUsageLimit Upsert cap
DeleteUsageLimit Remove cap

Paid checkout tiers: starter, hobbyist, developer, team, business (not free).

IntegrationService

Connect third-party accounts to a deployment (OAuth or credentials).

RPC Description
ListIntegrationProviders Catalog with configured flag
ListDeploymentIntegrations Connections for deployment
StartIntegrationOAuth Begin OAuth (redirectUri = admin callback)
CompleteIntegrationOAuth Exchange code (admin callback route)
ConnectIntegrationWithCredentials API key / app password providers
DisconnectIntegration Revoke connection

Credential maps are provider-specific (api_key, apple_id + app_password, etc.) and are never echoed back.

Dashboard OAuth callbacks use URLs under https://www.clusterclaw.ai/api/integrations/oauth/callback.

MeteringService

Low-level usage reporting and per-deployment aggregates.

RPC Typical caller Description
ReportUsage Internal/platform Insert usage event
BatchReportUsage Internal/platform Batch insert
GetDeploymentUsage Customer tooling Aggregates by deployment + period

GetDeploymentUsage request:

1
2
3
4
5
{
  "deploymentId": "…",
  "periodStart": "2026-06-01T00:00:00Z",
  "periodEnd": "2026-06-30T23:59:59Z"
}

Prefer BillingService.GetUsageSummary for account-level billing views.

Client libraries

Go SDK (packages/client-sdk)

1
2
client := sdk.NewClient("https://api.clusterclaw.ai", sdk.WithAPIKey(os.Getenv("CLUSTERCLAW_API_KEY")))
resp, err := client.Deployments.ListDeployments(ctx, connect.NewRequest(&openclawv1.ListDeploymentsRequest{}))

Wraps DeploymentService and CatalogService. Other services use generated Connect clients (see clients/cli).

CLI (claw)

1
2
3
4
claw signup --name acme --tier developer
claw deploy create --name prod --region us-central1
claw deploy list
claw usage

Config: ~/.clusterclaw/config.json, env CLUSTERCLAW_API_KEY.

Versioning and compatibility

  • Breaking RPC or field changes are announced in release notes.
  • Tag releases should include regenerated OpenAPI when protos change.
  • JSON field names use lowerCamelCase (protobuf JSON mapping).

Interactive reference

Local Backstage customer portal:

1
cd apps/backstage && yarn start:customer

Open OpenClaw v1 API (Connect) → View API, or browse TechDocs on OpenClaw Customer Documentation.

Published docs: docs.clusterclaw.ai.