API Reference

API Overview

Introduction to the FlatRun REST API.

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.

Live API Description

Each agent publishes the API it actually runs at /api/openapi.json. The description includes request fields, field types, accepted values, required permissions, response shapes, and whether an operation supports a plan. Use this document as the authoritative reference for the installed agent version. 

curl https://panel.example.com/api/openapi.json \
  -H "Authorization: Bearer $TOKEN" | jq

The CLI reads the same description. Run flatrun RESOURCE OPERATION --help for one operation, or --generate-cli-skeleton to print a request body you can fill in.

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

API data and errors use JSON. Download and stream endpoints return the media type described by OpenAPI. Successful JSON responses commonly 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

Object Stores

  • GET /backup-destinations: List stores
  • POST /object-stores/provision-managed: Deploy a store on this host
  • GET /object-stores/:name/objects: Browse a store
  • POST /object-stores/:name/replicate: Copy one store to another

Plans

  • GET /plans: List plans
  • GET /plans/:id: Read a preview
  • POST /plans/:id/apply: Run the reviewed change

Metrics & Alerts

  • GET /plugin/observability/metrics/latest: Current readings
  • GET /plugin/observability/metrics/timeseries: History for a deployment
  • GET /plugin/observability/alerts/rules: Alert rules
  • GET /dashboards: Saved dashboards

System

  • GET /health: Health check
  • GET /stats: System statistics
  • GET /settings: Get settings
  • PUT /settings: Update settings
  • GET /system/logs: Proxy and infrastructure logs
  • GET /notifications/targets: Delivery targets

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

API Documentation

Authentication API key and JWT auth Endpoints Complete endpoint reference
Star us on GitHub