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",
  "compose_content": "services:\n  app:\n    image: nginx:alpine\n",
  "env_vars": [{"key": "APP_ENV", "value": "staging"}],
  "auto_start": true
}

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

• tail: Number of lines (default: 100, 0 for all)
• service: One compose service, or omit for every service
• source: stdout for container output, or the id of a file source
• filter: Keep only lines containing this text

Follow deployment logs over a websocket, taking the same query parameters. The auth token is sent as the first message.

List the log sources offered for a deployment: container output, the built-in file sources for its kind, and any custom ones.

Add or replace custom file sources. Paths are relative to the deployment directory.

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",
  "container_port": 80,
  "path_prefix": "/",
  "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 the object stores this agent knows about, external and FlatRun-managed.

Deploy an object store on this host from a template and register it, credentials included.

List a store's buckets. POST the same path to create one, DELETE /api/object-stores/:name/buckets/:bucket to remove one.

List objects. POST uploads, GET /objects/download downloads, DELETE /objects removes.

Give a deployment this store's endpoint and credentials so the application can use it.

Sync this store to another one, for an offsite copy or a local cache.

List plans and their status.

Get one plan, with sensitive values redacted.

Run the reviewed change. Refused with 409 if a file it depends on changed since the plan was created, and with 410 once the plan has expired.

Discard a plan.

The most recent reading for every container, grouped by deployment.

History for one deployment. /metrics/host does the same for the host, /metrics/series for a single container and metric.

The same readings in the Prometheus text exposition format, for scraping.

Alert rules. PUT the same path to replace them. /alerts/firing is what is breached now, /alerts/events the history.

Each container's health. /health/events lists the recoveries the watcher performed.

Saved dashboards. POST to create, GET /api/dashboards/:id to read one, DELETE to remove.

Delivery targets as shoutrrr URLs, covering webhooks, chat services, and email. PUT to replace them.

Send a test message, so a target is known to work before an incident depends on it.

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": "[email protected]",
  "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"
}

List the host's own log sources: the proxy's access and error logs, and shared infrastructure containers.

Read a system log source.

Query Parameters

• source: Source id, for example nginx-access
• tail: Number of lines (default: 100, 0 for all)
• filter: Keep only lines containing this text
• deployment: Keep only the access lines for one deployment's domains

Follow a system log source over a websocket, taking the same query parameters.

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.