Endpoints Reference

List all deployments.

Response

[
  {
    "name": "my-wordpress",
    "path": "/var/flatrun/deployments/my-wordpress",
    "status": "running",
    "created_at": "2024-01-01T00:00:00Z",
    "services": [
      {"name": "wordpress", "status": "running", "health": "healthy"}
    ]
  }
]

Get detailed information about a specific deployment.

Parameters

• name — Deployment name

Create a new deployment.

Request Body

{
  "name": "my-app",
  "template_id": "wordpress",  // Optional: use template
  "compose": "...",            // Optional: raw compose content
  "port": 8080,                // Optional: external port
  "auto_start": true           // Optional: start after creation
}

Start a stopped deployment.

Stop a running deployment.

Restart a deployment.

Delete a deployment.

Query Parameters

• remove_files — Also delete deployment directory (default: false)

Get deployment logs.

Query Parameters

• service — Filter by service name
• tail — Number of lines (default: 100)
• follow — Stream logs (SSE)

Get resource usage statistics for all containers in deployment.

List all domains configured for a deployment.

Add a new domain to a deployment.

Request Body

{
  "service": "web",
  "domain": "blog.example.com",
  "port": 80,
  "path": "/",
  "strip_prefix": false,
  "ssl": {
    "enabled": true
  },
  "aliases": ["www.blog.example.com"]
}

Update an existing domain configuration.

Remove a domain from a deployment.

List all Docker containers.

Query Parameters

• all — Include stopped containers (default: true)

Start a container.

Stop a container.

Restart a container.

Remove a container (must be stopped).

Get container logs.

List all available templates.

Get template categories with counts.

Reload templates from disk.

Get template's docker-compose.yml content.

List all SSL certificates.

Request a new SSL certificate.

Request Body

{
  "domain": "example.com"
}

Renew all expiring certificates.

Delete a certificate.

Get proxy configuration status for a deployment.

Configure reverse proxy for a deployment.

Request Body

{
  "domain": "app.example.com",
  "port": 80,
  "ssl": true
}

Remove proxy configuration.

Test database connection.

List all databases on the server.

List tables in a database.

Request Body

{
  "database": "myapp"
}

Execute a SQL query.

Request Body

{
  "database": "myapp",
  "query": "SELECT * FROM users LIMIT 10"
}

Create a new database.

Create a database user.

Grant privileges to a user.

List infrastructure services.

Start an infrastructure service.

Stop an infrastructure service.

Get security statistics overview.

List security events with pagination and filtering.

Query Parameters

• type — Filter by event type
• source_ip — Filter by source IP
• deployment — Filter by deployment
• start_time — Start of time range (RFC3339)
• end_time — End of time range (RFC3339)
• limit — Number of results (default: 50)
• offset — Pagination offset

Get a single security event by ID.

Remove old security events.

Request Body

{
  "older_than": 604800  // Seconds
}

List all blocked IP addresses.

Block an IP address.

Request Body

{
  "ip": "192.168.1.100",
  "reason": "Suspicious activity",
  "duration": 86400  // Seconds (optional)
}

Unblock an IP address.

Get all security events for a specific IP.

List all protected routes.

Add a protected route.

Request Body

{
  "path": "/admin",
  "method": "ALL",
  "auth_type": "basic",
  "credentials": "admin:secret",
  "deployment": "my-app"
}

Update a protected route.

Delete a protected route.

List whitelist entries.

Add a whitelist entry.

Request Body

{
  "type": "ip",  // ip, cidr, or path
  "value": "10.0.0.0/8",
  "description": "Internal network"
}

Remove a whitelist entry.

Get real-time capture status.

Enable or disable real-time capture.

Request Body

{
  "enabled": true
}

Regenerate Lua scripts and reload nginx.

Get security settings for a deployment.

Update deployment security settings.

List all backups.

Query Parameters

• deployment — Filter by deployment name

Get backup details.

Create a backup.

Request Body

{
  "deployment_name": "my-wordpress",
  "include_files": true,
  "include_database": true,
  "exclude_patterns": ["*.log", "cache/*"],
  "description": "Pre-upgrade backup"
}

Response

{
  "job_id": "backup-123456",
  "message": "Backup job started"
}

Delete a backup.

Download backup archive.

Restore from a backup.

Request Body

{
  "target_name": "my-wordpress",
  "restore_database": true,
  "restore_files": true,
  "auto_start": true
}

List backup/restore jobs.

Get job status.

List backups for a deployment.

Get backup configuration for a deployment.

Update backup configuration for a deployment.

Request Body

{
  "enabled": true,
  "schedule": "0 2 * * *",
  "retention": 7,
  "include_database": true,
  "exclude_patterns": ["*.log"]
}

List scheduled tasks.

Query Parameters

• deployment — Filter by deployment name

Get scheduled task details.

Create a scheduled task.

Request Body

{
  "deployment_name": "my-wordpress",
  "task_type": "backup",
  "cron_expr": "0 2 * * *",
  "action": "",
  "description": "Daily backup at 2 AM"
}

Update a scheduled task.

Delete a scheduled task.

Execute a task immediately.

Get execution history for a task.

Get recent executions across all tasks.

Get current authenticated user.

Update current user profile.

Change current user password.

Request Body

{
  "current_password": "old-password",
  "new_password": "new-password"
}

List all users (admin only).

Get user details.

Create a new user.

Request Body

{
  "username": "john",
  "email": "john@example.com",
  "password": "secure-password",
  "role": "operator",
  "permissions": ["deployments:read", "deployments:write"]
}

Update a user.

Delete a user.

Get deployments assigned to a user.

Assign a deployment to a user.

Request Body

{
  "deployment_name": "my-app",
  "access_level": "write"  // read, write, or admin
}

Update deployment access level for a user.

Remove deployment access from a user.

Get users with access to a deployment.

List API keys (user's own keys or all if admin).

Get API key details.

Create a new API key.

Request Body

{
  "name": "CI/CD Key",
  "description": "For GitHub Actions",
  "role": "operator",
  "permissions": ["deployments:read", "deployments:write"],
  "deployments": ["my-app", "my-api"],
  "expires_in": 2592000  // Seconds (optional)
}

Response

{
  "id": 1,
  "key": "flatrun_xxxxxxxxxxxx",  // Only shown once
  "name": "CI/CD Key",
  "created_at": "2024-01-01T00:00:00Z"
}

Delete an API key.

Revoke an API key (deactivate without deleting).

Get traffic logs with filtering.

Query Parameters

• deployment — Filter by deployment
• method — HTTP method (GET, POST, etc.)
• status_group — Status group (2xx, 4xx, 5xx)
• status_code — Specific status code
• source_ip — Source IP address
• path — URL path pattern
• start_time — Start of time range (RFC3339)
• end_time — End of time range (RFC3339)
• limit — Number of results (default: 100)
• offset — Pagination offset

Get aggregated traffic statistics.

Get traffic stats for unknown domains.

Remove old traffic logs.

Get traffic stats for a specific deployment.

List audit events with filtering.

Query Parameters

• actor_id — Filter by actor ID
• actor_type — Filter by actor type (user, api_key, system)
• action — Filter by action
• resource_type — Filter by resource type
• resource_id — Filter by resource ID
• success — Filter by success status
• client_ip — Filter by client IP
• start_time — Start of time range (RFC3339)
• end_time — End of time range (RFC3339)
• limit — Number of results (default: 50, max: 1000)
• offset — Pagination offset

Get a single audit event.

Get audit statistics.

Export audit events.

Request Body

{
  "format": "json",  // or "csv"
  "actor_type": "user",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-31T23:59:59Z",
  "limit": 1000
}

Remove old audit events.

List available DNS providers.

Get PowerDNS service status.

Enable PowerDNS service.

Disable PowerDNS service.

Restart PowerDNS service.

List DNS zones.

Create a DNS zone.

Request Body

{
  "name": "example.com.",
  "kind": "Master",
  "nameservers": [
    "ns1.example.com.",
    "ns2.example.com."
  ]
}

Get zone details with records.

Delete a DNS zone.

Update zone records (RRSets).

Request Body

{
  "rrsets": [
    {
      "name": "www.example.com.",
      "type": "A",
      "ttl": 3600,
      "changetype": "REPLACE",
      "records": [
        {"content": "192.168.1.100", "disabled": false}
      ]
    }
  ]
}

List available plugins.

Get plugin details.

Create a deployment from a plugin.

List registry configurations.

Get registry details.

Create a registry configuration.

Update a registry configuration.

Delete a registry configuration.

List credentials.

Get credential details.

Create a credential.

Request Body

{
  "name": "docker-hub",
  "type": "docker-registry",
  "credentials": {
    "username": "myuser",
    "password": "mytoken"
  }
}

Update a credential.

Delete a credential.

Test credential validity.

Health check endpoint (no auth required).

Response

{
  "status": "ok",
  "version": "0.1.4",
  "uptime": "24h30m"
}

Get current agent settings.

Update agent settings.

Update security settings.

Get current authentication status.

Authenticate and get a token.

Request Body

{
  "username": "admin",
  "password": "password"
}

Validate current token.