API Overview

The FlatRun Agent exposes a comprehensive REST API for programmatic control of your deployments and infrastructure. This enables automation, integration with CI/CD pipelines, and building custom tooling.

Base URL

All API endpoints are relative to your agent's address:

http://localhost:8090/api

In production, use HTTPS and your configured domain.

Authentication

All API endpoints (except health and auth status) require authentication. See Authentication for details.

Quick Start

# Login and get token
TOKEN=$(curl -s -X POST http://localhost:8090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-api-key"}' | jq -r '.token')

# Use token in requests
curl http://localhost:8090/api/deployments \
  -H "Authorization: Bearer $TOKEN"

Response Format

All responses are JSON. Successful responses typically include:

{
  "data": { ... },    // or array for list endpoints
  "message": "Success"
}

Error responses include:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created (for POST requests)
400	Bad Request (invalid parameters)
401	Unauthorized (missing/invalid token)
404	Not Found
500	Internal Server Error

API Categories

The API is organized into the following categories:

Authentication

• GET /auth/status — Check if auth is enabled
• POST /auth/login — Login with API key
• GET /auth/validate — Validate JWT token

Deployments

• GET /deployments — List all deployments
• GET /deployments/:name — Get deployment details
• POST /deployments — Create deployment
• PUT /deployments/:name — Update deployment
• DELETE /deployments/:name — Delete deployment
• POST /deployments/:name/start — Start deployment
• POST /deployments/:name/stop — Stop deployment
• POST /deployments/:name/restart — Restart deployment
• GET /deployments/:name/logs — Get deployment logs
• GET /deployments/:name/stats — Get resource stats

Containers

• GET /containers — List all containers
• POST /containers/:id/start — Start container
• POST /containers/:id/stop — Stop container
• POST /containers/:id/restart — Restart container
• DELETE /containers/:id — Remove container
• GET /containers/:id/logs — Get container logs

Docker Resources

• GET /images — List images
• POST /images/pull — Pull image
• DELETE /images/:id — Delete image
• GET /volumes — List volumes
• POST /volumes — Create volume
• DELETE /volumes/:name — Delete volume
• GET /networks — List networks
• POST /networks — Create network
• DELETE /networks/:name — Delete network

Templates

• GET /templates — List templates
• GET /templates/categories — Get categories
• POST /templates/refresh — Refresh templates
• GET /templates/:id/compose — Get template compose

Certificates

• GET /certificates — List certificates
• POST /certificates — Request certificate
• POST /certificates/renew — Renew certificates
• DELETE /certificates/:domain — Delete certificate

Proxy

• GET /proxy/status/:name — Get proxy status
• POST /proxy/setup/:name — Setup proxy
• DELETE /proxy/:name — Remove proxy
• GET /proxy/vhosts — List virtual hosts

Databases

• POST /databases/test — Test connection
• POST /databases/list — List databases
• POST /databases/tables — List tables
• POST /databases/query — Execute query
• POST /databases/create — Create database
• POST /databases/users/create — Create user

Infrastructure

• GET /infrastructure — List infrastructure
• POST /infrastructure/:name/start — Start service
• POST /infrastructure/:name/stop — Stop service
• GET /infrastructure/:name/logs — Get logs

System

• GET /health — Health check
• GET /stats — System statistics
• GET /settings — Get settings
• PUT /settings — Update settings

Rate Limiting

The API does not currently implement rate limiting. However, for production use, it's recommended to place the agent behind a reverse proxy with rate limiting configured.

CORS

CORS can be enabled in the agent configuration to allow browser-based access from allowed origins:

api:
  enable_cors: true
  allowed_origins:
    - https://dashboard.example.com