API Overview

The better-openclaw REST API lets you programmatically generate OpenClaw stacks, validate configurations, and browse available services and skill packs. Use it to build integrations, CI/CD pipelines, or custom UIs.

Base URL

The API is available at the web application's base URL. In development, that's typically:

http://localhost:3000/api

In production:

https://better-openclaw.dev/api

All endpoints are prefixed with /api followed by the version (currently /v1), giving you a full base URL of:

https://better-openclaw.dev/api/v1

Authentication

The public API endpoints (listing services, skill packs, and presets) do not require authentication. For stack generation endpoints, you need an API key.

Getting an API Key

Set the OPENCLAW_API_KEY environment variable in your deployment's .env file to enable authentication:

# .env
OPENCLAW_API_KEY=your-secret-api-key-here

Using the API Key

Pass the API key in the Authorization header:

curl -X POST https://better-openclaw.dev/api/v1/generate \
  -H "Authorization: Bearer your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"preset": "researcher"}'

Public vs Protected Endpoints

Endpoint	Auth Required
`GET /v1/health`	No
`GET /v1/services`	No
`GET /v1/skills`	No
`GET /v1/presets`	No
`POST /v1/validate`	Yes
`POST /v1/generate`	Yes
`GET /v1/presets/:name`	No

Rate Limiting

The API enforces rate limits to prevent abuse:

Endpoint Type	Limit	Window
Read (GET)	100 requests	Per minute
Write (POST)	20 requests	Per minute
Generate	5 requests	Per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1700000000

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Response Format

All responses are JSON. Successful responses follow this structure:

{
  "ok": true,
  "data": { ... }
}

Error responses:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Service 'invalid-service' does not exist",
    "details": { ... }
  }
}

Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body or parameters
401	`UNAUTHORIZED`	Missing or invalid API key
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Conflicting services selected
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error

Quick Example

# List all available services
curl https://better-openclaw.dev/api/v1/services | jq

# Generate a stack
curl -X POST https://better-openclaw.dev/api/v1/generate \
  -H "Authorization: Bearer $OPENCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-stack",
    "preset": "researcher",
    "proxy": "caddy",
    "domain": "ai.example.com"
  }'

Next Steps

All Endpoints — full request and response reference
Service Catalog — browse available services
Skill Packs — curated skill bundles