Automation API

The Automation API (/api/automation/v1/) lets external systems execute operations on your servers. It’s designed for CI/CD integration — GitHub Actions, GitLab CI, Jenkins, or any system that can make HTTP requests.

For a setup guide with GitHub Actions, see GitHub Actions Integration.

Authentication

All requests require an Automation API key in the Authorization header:

Authorization: Bearer rca_your_key_here

Create keys in the dashboard: navigate to API Keys, select the Automation Keys tab, and click Create Key. Keys are scoped to specific servers and operations. See API Overview for the difference between API keys and automation keys.

Endpoints

Execute Command

POST /api/automation/v1/exec

Run a shell command on a server via the runner agent.

Request:

{
  "server_id": "uuid",
  "command": "docker compose up -d",
  "working_directory": "/opt/app",
  "env": {
    "DB_URL": "postgres://...",
    "API_KEY": "secret"
  },
  "timeout_seconds": 300,
  "run_id": "github-run-12345",
  "run_context": {
    "provider": "github_actions",
    "repository": "myorg/myapp",
    "workflow": "deploy",
    "trigger": "push",
    "actor": "username",
    "sha": "abc123",
    "ref": "refs/heads/main"
  }
}

Field	Required	Default	Description
server_id	Yes	-	Target server ID
command	Yes	-	Shell command (max 8,192 chars)
working_directory	No	-	Working directory on the server
env	No	-	Environment variables (max 200 keys, 64KB total)
timeout_seconds	No	60	Max execution time (1-900 seconds)
run_id	No	-	Groups related operations (e.g., GitHub run ID)
run_context	No	-	CI metadata for audit trail

Response (completed):

{
  "operation_id": "uuid",
  "status": "completed",
  "exit_code": 0,
  "stdout": "...",
  "stderr": "",
  "duration_ms": 4500
}

Response (still running):

{
  "operation_id": "uuid",
  "status": "running"
}

If the command finishes within timeout_seconds, the full result is returned. Otherwise, poll the operation status endpoint.

Trigger Deployment

POST /api/automation/v1/deploy

Trigger a deployment for an application.

Request:

{
  "application_id": "uuid",
  "commit_ref": "main",
  "env_overrides": {
    "FEATURE_FLAG": "true"
  },
  "run_id": "github-run-12345",
  "run_context": { ... }
}

Field	Required	Default	Description
application_id	Yes	-	Application to deploy
commit_ref	No	App’s deploy branch	Branch, tag, or SHA
env_overrides	No	-	Ephemeral env vars for this deployment only (not saved)
timeout_seconds	No	60	Max wait time
run_id	No	-	Groups related operations
run_context	No	-	CI metadata

Response:

{
  "operation_id": "uuid",
  "status": "running",
  "deployment_id": "uuid"
}

Deployments are always async. Poll the operation status for completion.

Restart Container

POST /api/automation/v1/restart

Restart an application’s Docker container.

Request:

{
  "server_id": "uuid",
  "container_name": "myapp",
  "run_id": "github-run-12345"
}

Reboot Server

POST /api/automation/v1/reboot

Reboot a server. Uses cloud provider API if available, falls back to runner.

Request:

{
  "server_id": "uuid",
  "run_id": "github-run-12345"
}

Registry Login

POST /api/automation/v1/registry-auth/login

Log in to a container registry on the target server using a registry credential stored in your Reoclo tenant. This endpoint is asynchronous. It creates an operation record and returns 202 immediately. Poll the operation status endpoint to track progress.

The plaintext registry password is never returned by the API. The response body contains only the resolved registry URL and registry provider type.

Request:

{
  "server_id": "uuid",
  "credential_id": "uuid",
  "run_id": "github-run-12345",
  "run_context": { "provider": "github_actions", "repository": "myorg/myapp", "...": "..." }
}

Field	Required	Description
server_id	Yes	Target server ID (must be runner-connected)
credential_id	Yes	Registry credential UUID. Must be in the key’s allowed_credential_ids if scoped.
run_id	No	Groups related operations
run_context	No	CI metadata for audit trail

Response (202 Accepted):

{
  "operation_id": "uuid",
  "status": "running",
  "registry_url": "ghcr.io",
  "registry_type": "ghcr"
}

Poll /operations/{operation_id} for the final result. When complete, the operation contains the exit_code, captured stdout, captured stderr, and duration_ms. Both the login and any subsequent logout are recorded in the audit log.

Registry Logout

POST /api/automation/v1/registry-auth/logout

Run docker logout on the target server. This is the paired cleanup for registry-auth/login, typically invoked from a GitHub Action post-step. Synchronous.

Request:

{
  "server_id": "uuid",
  "registry_url": "ghcr.io",
  "run_id": "github-run-12345"
}

Response:

{
  "operation_id": "uuid",
  "status": "completed"
}

Logout failures do not return HTTP 5xx. They return a completed operation with a non-zero exit code. Clients should log them as warnings, not errors.

Poll Operation Status

GET /api/automation/v1/operations/{operation_id}

Check the status of a running operation.

Response:

{
  "operation_id": "uuid",
  "operation_type": "exec",
  "server_id": "uuid",
  "server_name": "prod-1",
  "status": "completed",
  "result": {
    "exit_code": 0,
    "stdout": "...",
    "stderr": "",
    "duration_ms": 4500
  },
  "run_id": "github-run-12345",
  "started_at": "2026-04-10T14:30:00Z",
  "completed_at": "2026-04-10T14:30:04Z"
}

Status values: running, completed, failed, timeout

API Key Scoping

Each automation key can be restricted to:

Scope	Description
Servers	Which servers the key can target. Empty = all servers.
Operations	Which operations are allowed: exec, deploy, restart, reboot, registry_login, registry_logout. Empty = all.
Registry credentials	Which registry credentials the key may pass to registry-auth/login. Empty = all credentials in the tenant. Cross-tenant references are rejected at create/update time.
IP allowlist	Restrict to specific IPs or CIDR ranges (e.g., GitHub runner IPs). Empty = allow all.
Rate limit	Requests per minute (default: 100, max: 1000).
Expiration	Optional expiry date for the key.

Rate Limiting

Each key has a configurable rate limit (default: 100 requests/minute). When exceeded:

• HTTP 429 Too Many Requests is returned
• Retry-After header indicates when to retry
• Rate limit events are logged in the audit trail

Environment Variables

Environment variables passed via env (for exec) or env_overrides (for deploy):

• Are injected into the command’s execution environment on the server
• Are never stored in Reoclo’s database
• Only key names appear in audit logs (values are redacted)
• Limited to 200 keys and 64KB total payload size

Audit Trail

Every operation is logged with:

• The command that was executed
• Which server it ran on
• Exit code, stdout, stderr
• Which API key was used
• CI context (repository, workflow, actor, commit SHA)

Operations from the same CI run are grouped by run_id. Click the operation count on any automation key row to view its operation history in Logs.

Error Responses

Code	Meaning
401	Invalid, revoked, or expired API key
403	Operation or server not in key’s scope; IP not in allowlist
404	Server or application not found
422	Validation error (env too large, invalid timeout, etc.)
429	Rate limit exceeded

All errors return:

{
  "detail": "Human-readable error message"
}

Next Steps

• GitHub Actions Integration for step-by-step setup with @reoclo/run
• API Overview for general API authentication
• Scheduled Operations for server-side automation without CI