API Overview

Reoclo provides programmatic access through API keys. The dashboard handles most operations, but you can automate workflows using the API directly.

For Your Organization

The dashboard handles most operations automatically. For programmatic access, use API keys.

Reoclo receives webhooks from GitHub (push events, installations, and so on). You do not need to configure webhooks manually. The GitHub App handles this automatically.

Authentication

Reoclo supports two authentication mechanisms, each with its own use case:

• OAuth 2.0 (device flow): for IDEs, MCP servers, scripts, and any interactive programmatic use. Run reoclo login to authenticate. The CLI handles token refresh automatically. No keys to mint or paste.
• Automation Keys (rca_ prefix): for CI/CD systems like GitHub Actions and unattended scripts. Scoped to specific servers and operations with optional IP allowlist and rate limiting. Create them from Automation Keys in the dashboard sidebar.

Tenant Integration Keys (rk_t_*) have been retired. Existing integrations should migrate to reoclo login for interactive use or Automation Keys for CI/CD. See the API Keys guide.

Example request (interactive)

After reoclo login, call the CLI directly:

reoclo servers ls -o json

Example request (Automation Key)

curl -X POST https://api.reoclo.com/api/automation/v1/exec \
  -H "Authorization: Bearer rca_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"server_id": "your-server-id", "command": "docker compose up -d"}'

Security

• API keys are scoped to an organization (you cannot access other organizations’ resources)
• API keys do not expire (until you revoke them)
• API keys can be revoked at any time in the dashboard
• Each key has a name for easy identification

Treat API Keys Like Passwords

API keys grant full access to your organization. Do not commit them to git, share them in Slack, or expose them in client-side code.

Store them in environment variables or a secrets manager (1Password, AWS Secrets Manager, and so on).

Revoking API Keys

If an API key is compromised:

1. Navigate to Settings → API Keys
2. Find the key in the list
3. Click “Revoke”

The key is invalidated immediately. Any requests using that key will fail with a 401 Unauthorized error.

Automation API

The Automation API is a versioned external API designed for CI/CD integration. It lets you execute operations on your servers from GitHub Actions, GitLab CI, Jenkins, or any system that can make HTTP requests.

Key differences from regular API keys:

	API Keys	Automation API Keys
Auth header	X-API-Key	Authorization: Bearer rca_...
Scope	Full organization access	Scoped to specific servers and operations
IP restriction	No	Optional IP allowlist
Rate limiting	Global (100 req/min)	Per-key, configurable (default 100 req/min)
Audit trail	Standard	Enhanced with CI run context

Create automation keys in the dashboard: navigate to API Keys, select the Automation Keys tab, and click Create Key.

For full endpoint documentation, see the Automation API reference.

For a step-by-step setup guide with GitHub Actions, see GitHub Actions Integration.

MCP Server

The Reoclo CLI’s embedded MCP server lets AI coding tools manage your infrastructure directly: servers, applications, deployments, domains, logs, monitors, status pages, and scheduled operations. It works with Claude Code, Cursor, Windsurf, VS Code, Zed, JetBrains, Cline, and any MCP-compatible client.

See the MCP Server Setup guide for step-by-step instructions for your editor.

Common Operations

Here are the most common operations you might want to automate:

List Servers

GET /api/servers

Returns all servers in your organization.

List Applications

GET /api/applications

Returns all applications in your organization.

Trigger a Deployment

POST /api/tenants/{tenant_id}/applications/{application_id}/deploy

Triggers a deployment for the specified application. This schedules the deployment and returns immediately. Poll the deployment status to see when it completes.

View Deployment History

GET /api/tenants/{tenant_id}/applications/{application_id}/deployments

Returns deployment history for the specified application, including status, duration, and commit information.

Manage Environment Variables

POST /api/tenants/{tenant_id}/applications/{application_id}/env

Add or update environment variables for an application. Remember that environment variables are write-only after saving. You cannot read them back.

Detailed API Reference Coming Soon

We plan to publish a comprehensive API endpoint reference with request/response schemas. For now, API keys provide programmatic access to the same operations available in the dashboard.

If you need to automate something that is not listed here, contact support for guidance.

Webhook Integration

Reoclo’s GitHub App receives webhooks automatically. You do not need to configure webhooks manually.

How It Works

1. You install the Reoclo GitHub App on your organization or repositories
2. GitHub sends webhooks to Reoclo when events occur (pushes, installations, and so on)
3. Reoclo processes the webhooks and takes action (for example, triggering auto-deploy on push)

Supported Events

• Push events: Trigger auto-deploy (if enabled for the application)
• Installation events: Manage repository access when you install or uninstall the GitHub App
• Repository events: Sync repository metadata when you add or remove repositories

All of this happens automatically. You do not need to configure webhook URLs or secrets.

Rate Limits

API requests are rate-limited to prevent abuse:

• The default limit is 240 requests per minute per client IP.
• Automation keys have a per-key limit. The default is 100 requests per minute. You can change it on the key.
• Account flows (password reset, access requests) have stricter limits.

Every response reports the current limit in two forms, so agents can self-throttle in real time:

RateLimit-Policy: "default";q=240;w=60
RateLimit: "default";r=239;t=42
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 239
X-RateLimit-Reset: 1787480000

The RateLimit and RateLimit-Policy fields follow the IETF draft-ietf-httpapi-ratelimit-headers format. In RateLimit-Policy, q is the quota and w is the window in seconds. In RateLimit, r is the remaining quota and t is the seconds until the window resets. The X-RateLimit-* set is the legacy equivalent.

If you exceed a limit, you get a 429 Too Many Requests response with a Retry-After header. Wait that many seconds before the next request.

For higher rate limits, contact support.

Machine-Readable Specification

The OpenAPI 3.1 specification for the public API lives at https://api.reoclo.com/openapi.json. It covers the automation API, OAuth, webhooks, and the discovery documents, with a named OAuth scope list in its security schemes.

Related discovery documents:

• /.well-known/oauth-authorization-server: OAuth server metadata (RFC 8414)
• /.well-known/oauth-protected-resource: protected resource metadata with the supported scopes (RFC 9728)

For the versioning rules and the deprecation policy, see API Versioning and Deprecation.

Next Steps

• MCP Server Setup for editor-specific setup instructions
• Generate your first API key to start automating deployments
• Automation API reference for CI/CD endpoint documentation
• GitHub Actions Integration to set up @reoclo/run and @reoclo/checkout
• Understand access control to see how API keys are scoped to organizations
• Set up auto-deploy to trigger deployments automatically on git push