Skip to main content

​
Introduction

The better-openclaw REST API allows you to programmatically generate Docker Compose stacks, list available services, browse presets, and validate configurations. It’s perfect for integrating stack generation into CI/CD pipelines, web applications, or custom tooling.

​
Base URL

The API runs on port 3456 with all endpoints prefixed with /v1: 
http://localhost:3456/v1
For production deployments, replace localhost:3456 with your deployed API host.

​
Quick Start

Generate a stack with PostgreSQL, Redis, and n8n: 
curl -X POST http://localhost:3456/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "my-stack",
    "services": ["postgresql", "redis", "n8n"],
    "proxy": "caddy",
    "domain": "example.com"
  }'
The response includes all generated files (docker-compose.yml, .env, etc.) as JSON.

​
API Features

  • Service Discovery - List all 94 available services with filtering by category and maturity
  • Preset Management - Browse 9 pre-configured stack templates
  • Stack Generation - Generate complete stacks with multiple output formats (JSON, ZIP)
  • Validation - Validate configurations before generation with dependency resolution
  • OpenAPI Spec - Auto-generated specification available at /v1/openapi.json
  • Interactive Docs - Swagger UI available at /v1/docs

​
Response Format

All responses use JSON with consistent error handling: Success Response: 
{
  "data": { /* endpoint-specific payload */ }
}
Error Response: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [ /* optional validation details */ ]
  }
}

​
Error Codes

CodeStatusDescription
UNAUTHORIZED401Missing or invalid API key
VALIDATION_ERROR400Invalid request parameters or body
NOT_FOUND404Resource not found
CONFLICT_ERROR409Configuration conflict (e.g., incompatible services)
GENERATION_ERROR500Stack generation failed
INTERNAL_ERROR500Unexpected server error

​
Rate Limiting

The API includes distributed rate limiting:
  • Standard endpoints: 100 requests per 15 minutes per IP
  • Generate endpoint: 10 requests per 15 minutes per IP
  • Authenticated requests: Higher limits (configured per API key)
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

​
CORS

CORS is enabled for all origins by default. For production, configure allowed origins via environment variables.

​
Health Check

Check API availability: 
curl http://localhost:3456/v1/health
Response: 
{
  "status": "ok",
  "version": "1.0.0"
}

​
Next Steps

Authentication

Learn how to authenticate your API requests

Services Endpoint

Browse and filter available services

Presets Endpoint

List preset stack configurations

Skills Endpoint

Discover skill packs for AI agents

Generate Endpoint

Generate complete Docker Compose stacks

Validate Endpoint

Validate configurations before generation

Build docs developers (and LLMs) love

Get started for freeTalk to us