config/skills/coolify-setup/references/api-integration.md

Coolify API Integration for CEO Agents

API Authentication

Coolify exposes a REST API at https://<coolify-domain>/api/v1/.

Creating API Tokens

1. Coolify UI → Settings → Keys & Tokens → API Tokens
2. Create one token per CEO agent/project
3. Tokens can be scoped — create project-level tokens so each CEO only sees its own resources

Using the API

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     https://coolify.cloonar.com/api/v1/<endpoint>

Key Endpoints

Deploy Application

POST /api/v1/deploy
Body: { "uuid": "<app-uuid>" }
# or by tag:
Body: { "tag": "<tag-name>" }

List Applications

GET /api/v1/applications

Get Application

GET /api/v1/applications/{uuid}

Update Application Environment

PATCH /api/v1/applications/{uuid}/envs
Body: { "key": "VAR_NAME", "value": "new_value" }

Application Actions

POST /api/v1/applications/{uuid}/start
POST /api/v1/applications/{uuid}/stop
POST /api/v1/applications/{uuid}/restart

Databases

GET /api/v1/databases
GET /api/v1/databases/{uuid}
POST /api/v1/databases/{uuid}/start
POST /api/v1/databases/{uuid}/stop

Servers

GET /api/v1/servers
GET /api/v1/servers/{uuid}
GET /api/v1/servers/{uuid}/resources

CEO Agent Integration Pattern

Each CEO agent should have a CLI helper script (like bin/docfast-deploy) that wraps the Coolify API:

#!/bin/bash
# Example: bin/docfast-deploy
source ~/.openclaw/workspace/.credentials/coolify.env
# COOLIFY_URL=https://coolify.cloonar.com
# COOLIFY_TOKEN=<project-scoped-token>
# DOCFAST_APP_UUID=<uuid>

curl -s -X POST \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"uuid\": \"$DOCFAST_APP_UUID\"}" \
  "$COOLIFY_URL/api/v1/deploy"

What CEO Agents Can Do via API

• Trigger deploys after code changes
• Check application status/health
• Restart services if unhealthy
• Update environment variables
• Monitor server resources (disk, memory)
• Scale up/down (start/stop additional instances)

What CEO Agents Should NOT Do

• Manage other projects' resources (token scoping prevents this)
• Delete servers or applications
• Modify infrastructure-level settings

Webhook Deploys (Alternative)

Instead of API-triggered deploys, Coolify supports webhook-based deploys:

1. In Coolify, enable webhook for the application
2. Get the webhook URL (unique per app)
3. Add as Forgejo webhook → auto-deploy on push

This is simpler for CI/CD but less controllable than API deploys.

Monitoring Integration

CEO agents can check their application's health:

# Get app status
curl -s -H "Authorization: Bearer $TOKEN" \
  "$COOLIFY_URL/api/v1/applications/$APP_UUID" | jq '.status'

# Get server resources
curl -s -H "Authorization: Bearer $TOKEN" \
  "$COOLIFY_URL/api/v1/servers/$SERVER_UUID" | jq '.settings'

Combine with existing uptime monitoring (health endpoint checks) for comprehensive monitoring.