# 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

```bash
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:

```bash
#!/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:

```bash
# 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.