API Reference

Endpoints Reference

Complete reference for all FlatRun API endpoints.

This page provides detailed documentation for all API endpoints. All endpoints require authentication unless otherwise noted.

Deployments

GET /api/deployments

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 /api/deployments/:name

Get detailed information about a specific deployment.

Parameters

  • name — Deployment name
POST /api/deployments

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
}
POST /api/deployments/:name/start

Start a stopped deployment.

POST /api/deployments/:name/stop

Stop a running deployment.

POST /api/deployments/:name/restart

Restart a deployment.

DELETE /api/deployments/:name

Delete a deployment.

Query Parameters

  • remove_files — Also delete deployment directory (default: false)
GET /api/deployments/:name/logs

Get deployment logs.

Query Parameters

  • service — Filter by service name
  • tail — Number of lines (default: 100)
  • follow — Stream logs (SSE)
GET /api/deployments/:name/stats

Get resource usage statistics for all containers in deployment.

Containers

GET /api/containers

List all Docker containers.

Query Parameters

  • all — Include stopped containers (default: true)
POST /api/containers/:id/start

Start a container.

POST /api/containers/:id/stop

Stop a container.

POST /api/containers/:id/restart

Restart a container.

DELETE /api/containers/:id

Remove a container (must be stopped).

GET /api/containers/:id/logs

Get container logs.

Templates

GET /api/templates

List all available templates.

GET /api/templates/categories

Get template categories with counts.

POST /api/templates/refresh

Reload templates from disk.

GET /api/templates/:id/compose

Get template's docker-compose.yml content.

Certificates

GET /api/certificates

List all SSL certificates.

POST /api/certificates

Request a new SSL certificate.

Request Body

{
  "domain": "example.com"
}
POST /api/certificates/renew

Renew all expiring certificates.

DELETE /api/certificates/:domain

Delete a certificate.

Proxy

GET /api/proxy/status/:name

Get proxy configuration status for a deployment.

POST /api/proxy/setup/:name

Configure reverse proxy for a deployment.

Request Body

{
  "domain": "app.example.com",
  "port": 80,
  "ssl": true
}
DELETE /api/proxy/:name

Remove proxy configuration.

Databases

POST /api/databases/test

Test database connection.

POST /api/databases/list

List all databases on the server.

POST /api/databases/tables

List tables in a database.

Request Body

{
  "database": "myapp"
}
POST /api/databases/query

Execute a SQL query.

Request Body

{
  "database": "myapp",
  "query": "SELECT * FROM users LIMIT 10"
}
POST /api/databases/create

Create a new database.

POST /api/databases/users/create

Create a database user.

POST /api/databases/privileges/grant

Grant privileges to a user.

Infrastructure

GET /api/infrastructure

List infrastructure services.

POST /api/infrastructure/:name/start

Start an infrastructure service.

POST /api/infrastructure/:name/stop

Stop an infrastructure service.

System

GET /api/health

Health check endpoint (no auth required).

Response

{
  "status": "ok",
  "version": "0.1.4",
  "uptime": "24h30m"
}
GET /api/settings

Get current agent settings.

PUT /api/settings

Update agent settings.