API Endpoints

Full reference for all REST API endpoints. All paths are relative to the base URL /api/v1. See the API Overview for authentication and rate limiting details.

GET /v1/health — Health Check

Returns the API status. Use for monitoring and uptime checks.

Request

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

Response 200 OK

{
  "ok": true,
  "data": {
    "status": "healthy",
    "version": "1.4.2",
    "uptime": 86400,
    "services": 58,
    "skillPacks": 10,
    "presets": 5
  }
}

GET /v1/services — List Services

Returns all available companion services grouped by category.

Query Parameters

Request

curl https://better-openclaw.dev/api/v1/services?category=database

Response 200 OK

{
  "ok": true,
  "data": {
    "total": 8,
    "services": [
      {
        "id": "qdrant",
        "name": "Qdrant",
        "description": "Vector database for embeddings and similarity search",
        "category": "database",
        "image": "qdrant/qdrant",
        "imageTag": "latest",
        "maturity": "stable",
        "ports": [{ "host": 6333, "container": 6333 }],
        "requires": [],
        "conflictsWith": [],
        "minMemoryMB": 256,
        "tags": ["vector", "embeddings", "rag"]
      }
      // ... more services
    ]
  }
}

GET /v1/skills — List Skill Packs

Returns all available skill packs with their descriptions and required services.

Request

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

Response 200 OK

{
  "ok": true,
  "data": {
    "total": 10,
    "skillPacks": [
      {
        "id": "researcher",
        "name": "Researcher",
        "description": "Web search, content extraction, and citation skills",
        "requiredServices": ["searxng", "browserless"],
        "optionalServices": ["qdrant"],
        "skills": [
          "web-search",
          "content-extract",
          "citation-builder",
          "fact-check"
        ]
      }
      // ... more skill packs
    ]
  }
}

GET /v1/presets — List Presets

Returns all preset configurations.

Request

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

Response 200 OK

{
  "ok": true,
  "data": {
    "presets": [
      {
        "id": "minimal",
        "name": "Minimal",
        "description": "OpenClaw + Redis for lightweight experimentation",
        "services": ["redis"],
        "skills": ["memory"]
      },
      {
        "id": "researcher",
        "name": "Researcher",
        "description": "Web research and RAG pipeline",
        "services": ["qdrant", "searxng", "browserless", "redis"],
        "skills": ["researcher", "memory"]
      }
      // ... more presets
    ]
  }
}

GET /v1/presets/:name — Get Preset Detail

Returns detailed information about a specific preset, including the full service and skill pack configuration.

Path Parameters

Request

curl https://better-openclaw.dev/api/v1/presets/researcher

Response 200 OK

{
  "ok": true,
  "data": {
    "id": "researcher",
    "name": "Researcher",
    "description": "Web research and RAG pipeline",
    "services": [
      { "id": "qdrant", "name": "Qdrant", "category": "database" },
      { "id": "searxng", "name": "SearXNG", "category": "search" },
      { "id": "browserless", "name": "Browserless", "category": "automation" },
      { "id": "redis", "name": "Redis", "category": "cache" }
    ],
    "skills": [
      { "id": "researcher", "name": "Researcher", "skillCount": 4 },
      { "id": "memory", "name": "Memory", "skillCount": 3 }
    ],
    "estimatedMemoryMB": 2048
  }
}

Response 404 Not Found

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Preset 'invalid-preset' does not exist"
  }
}

POST /v1/validate — Validate Configuration

Validates a stack configuration without generating any files. Useful for checking for conflicts, missing dependencies, and invalid options before generating.

Request Body

Request

curl -X POST https://better-openclaw.dev/api/v1/validate \
  -H "Authorization: Bearer $OPENCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "services": ["qdrant", "redis", "milvus"],
    "skills": ["researcher"]
  }'

Response 200 OK (valid)

{
  "ok": true,
  "data": {
    "valid": true,
    "warnings": [
      {
        "code": "CONFLICT",
        "message": "qdrant and milvus are both vector databases; consider using only one"
      }
    ],
    "resolvedServices": ["openclaw", "qdrant", "redis", "milvus", "searxng", "browserless"],
    "resolvedSkills": ["researcher"],
    "estimatedMemoryMB": 3072
  }
}

Response 400 Bad Request (invalid)

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid configuration",
    "details": {
      "errors": [
        "Service 'invalid-service' does not exist",
        "Skill pack 'researcher' requires 'searxng' which is not selected"
      ]
    }
  }
}

POST /v1/generate — Generate Stack

Generates a complete stack configuration and returns the files as a JSON bundle or downloadable archive.

Request Body

Request

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"
  }'

Response 200 OK (format: json)

{
  "ok": true,
  "data": {
    "name": "my-stack",
    "files": {
      "docker-compose.yml": "version: '3.8'\nservices:\n  ...",
      ".env.example": "# OpenClaw Configuration\nOPENAI_API_KEY=\n...",
      "Caddyfile": "ai.example.com {\n  reverse_proxy openclaw:8080\n}",
      "configs/openclaw/config.yaml": "gateway:\n  port: 8080\n...",
      "scripts/start.sh": "#!/bin/bash\n...",
      "scripts/stop.sh": "#!/bin/bash\n...",
      "scripts/update.sh": "#!/bin/bash\n...",
      "scripts/backup.sh": "#!/bin/bash\n...",
      "scripts/status.sh": "#!/bin/bash\n...",
      "README.md": "# my-stack\n..."
    },
    "summary": {
      "services": 5,
      "skills": 2,
      "proxy": "caddy",
      "estimatedMemoryMB": 2048
    }
  }
}

Download as Tar Archive

Set format: "tar" to get a downloadable .tar.gz archive instead of JSON:

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", "format": "tar"}' \
  -o my-stack.tar.gz

Next Steps

• API Overview — authentication and general concepts
• Service Catalog — browse all services
• CLI Reference — generate stacks from the command line