Skip to content

API Documentation

Jump to bottom
Casey edited this page Jul 29, 2025 · 1 revision

API Documentation

See More

This comprehensive reference covers all REST API endpoints available in Flowcase, including authentication, request/response formats, and practical examples.

[!INFO] Implementation Status: This documentation covers both implemented and planned API endpoints. Features marked as "planned" or "future" are not yet available in the current version.

🌐 API Overview

Base URL

http://your-flowcase-instance.com

Authentication

All API endpoints require authentication via session cookies obtained through login.

Response Format

All responses follow a consistent JSON format:

{
  "success": true|false,
  "data": {},
  "error": "Error message if success is false"
}

🔐 Authentication

Login

Authenticate to obtain session cookies for API access.

POST /login
Content-Type: application/x-www-form-urlencoded

username=your_username&password=your_password&remember=on

Note: The login endpoint expects form data, not JSON. The remember parameter is optional.

Response:

  • Success: HTTP 302 redirect to /dashboard with session cookies
  • Error: HTTP 302 redirect to / with error in session

Note: The login endpoint does NOT return JSON responses. It uses traditional form submission with redirects. Check the redirect location to determine success/failure.

Session Cookies Set:

  • userid - User ID
  • username - Username
  • token - User auth token
  • Flask session cookie

Logout

Terminate the current session.

GET /logout

Response:

  • HTTP 302 redirect to / with cookies cleared

Droplet Connection Auth

Verify authentication for droplet access.

GET /droplet_connect

Required Cookies: userid, token

Response:

  • 200: Valid authentication
  • 401: Invalid or missing authentication

🌊 Droplet Endpoints

Get Available Droplets

Retrieve list of droplets available to the current user.

GET /api/droplets

Response:

{
  "success": true,
  "droplets": [
    {
      "id": "droplet-uuid",
      "display_name": "Ubuntu Desktop",
      "description": "Full Ubuntu desktop environment",
      "image_path": "/static/img/ubuntu.jpg",
      "droplet_type": "container",
      "container_docker_image": "ubuntu:20.04-desktop",
      "container_docker_registry": "https://index.docker.io/v1/",
      "container_cores": 2,
      "container_memory": 2048,
      "server_ip": null,
      "server_port": null
    }
  ]
}

🚀 Instance Management

Get User Instances

Retrieve all instances owned by the current user.

GET /api/instances

Response:

{
  "success": true,
  "instances": [
    {
      "id": "instance-uuid",
      "created_at": "2024-01-15T10:30:00.000000",
      "updated_at": "2024-01-15T10:35:00.000000",
      "droplet": {
        "id": "droplet-uuid",
        "display_name": "Ubuntu Desktop",
        "description": "Full Ubuntu desktop environment",
        "image_path": "/static/img/ubuntu.jpg",
        "droplet_type": "container",
        "container_docker_image": "ubuntu:20.04-desktop",
        "container_docker_registry": "https://index.docker.io/v1/",
        "container_cores": 2,
        "container_memory": 2048,
        "server_ip": null,
        "server_port": null
      }
    }
  ]
}

Request New Instance

Create a new droplet instance.

POST /api/instance/request
Content-Type: application/json

{
  "droplet_id": "droplet-uuid",
  "resolution": "1920x1080"
}

Response:

{
  "success": true,
  "instance_id": "new-instance-uuid",
  "guac_token": "encrypted-token-string",
  "redirect": "/droplet/new-instance-uuid"
}

Destroy Instance

Terminate and remove an instance.

GET /api/instance/{instance_id}/destroy

Response:

{
  "success": true,
  "message": "Instance destroyed successfully"
}

Access Instance

Get the droplet interface for an instance.

GET /droplet/{instance_id}

Response: HTML page with embedded instance interface and VNC viewer

Get Dashboard

Access the main dashboard page (requires authentication).

GET /dashboard

Response: HTML page with dashboard interface and available droplets

👥 Admin API - System Information

Get System Info

Retrieve system status and statistics (requires perm_admin_panel).

GET /api/admin/system_info

Response:

{
  "success": true,
  "system": {
    "hostname": "flowcase-host",
    "os": "Linux 5.4.0"
  },
  "version": {
    "flowcase": "develop",
    "python": "3.11.2",
    "docker": "24.0.7",
    "nginx": "1.28.1"
  }
}

Get Health Status

Check system health and status.

GET /health

Warning

Planned Feature: The /health endpoint is not yet implemented in the current version. System health information is available through the Admin Panel → System Information instead.

Response:

{
  "status": "healthy",
  "version": "develop",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "database": "ok",
    "docker": "ok",
    "storage": "ok"
  }
}

👥 Admin API - User Management

List Users

Retrieve all users (requires perm_view_users).

GET /api/admin/users

Response:

{
  "success": true,
  "users": [
    {
      "id": "user-uuid",
      "username": "admin",
      "created_at": "2024-01-15T10:30:00.000000",
      "groups": ["admin-group-uuid", "user-group-uuid"]
    }
  ]
}

Create/Update User

Create or modify a user account (requires perm_edit_users).

POST /api/admin/user
Content-Type: application/json

{
  "username": "newuser",
  "password": "secure_password",
  "groups": "user-group-uuid,admin-group-uuid"
}

For updates, include:

{
  "user_id": "existing-user-uuid",
  "username": "updated_username",
  "groups": "user-group-uuid",
  "new_password": "new_password"
}

Response:

{
  "success": true,
  "message": "User created/updated successfully"
}

Delete User

Remove a user account (requires perm_edit_users).

DELETE /api/admin/user
Content-Type: application/json

{
  "user_id": "user-uuid"
}

Response:

{
  "success": true,
  "message": "User deleted successfully"
}

🎛️ Admin API - Droplet Management

List All Droplets

Retrieve all droplets in the system (requires perm_view_droplets).

GET /api/admin/droplets

Response:

{
  "success": true,
  "droplets": [
    {
      "id": "droplet-uuid",
      "display_name": "Ubuntu Desktop",
      "description": "Full Ubuntu desktop environment",
      "image_path": "/static/img/ubuntu.jpg",
      "droplet_type": "container",
      "container_docker_image": "ubuntu:20.04-desktop",
      "container_docker_registry": "https://index.docker.io/v1/",
      "container_cores": 2,
      "container_memory": 2048,
      "container_persistent_profile_path": "/home/user",
      "server_ip": null,
      "server_port": null,
      "server_username": null,
      "server_password": "********************************"
    }
  ]
}

Create/Update Droplet

Add or modify a droplet (requires perm_edit_droplets).

POST /api/admin/droplet
Content-Type: application/json

{
  "display_name": "New Application",
  "description": "Application description",
  "droplet_type": "container",
  "container_docker_image": "myapp:latest",
  "container_docker_registry": "https://registry.company.com",
  "container_cores": 1,
  "container_memory": 1024,
  "container_persistent_profile_path": "/home/user"
}

Response:

{
  "success": true,
  "message": "Droplet created/updated successfully"
}

Delete Droplet

Remove a droplet from the system (requires perm_edit_droplets).

DELETE /api/admin/droplet
Content-Type: application/json

{
  "droplet_id": "droplet-uuid"
}

Response:

{
  "success": true,
  "message": "Droplet deleted successfully"
}

👥 Admin API - Instance Management

List All Instances

Retrieve all instances in the system (requires perm_view_instances).

GET /api/admin/instances

Response:

{
  "success": true,
  "instances": [
    {
      "id": "instance-uuid",
      "user": {
        "username": "user1"
      },
      "droplet": {
        "display_name": "Ubuntu Desktop"
      },
      "created_at": "2024-01-15T10:30:00.000000",
      "updated_at": "2024-01-15T10:35:00.000000"
    }
  ]
}

Force Destroy Instance

Forcefully terminate any instance (requires perm_edit_instances).

DELETE /api/admin/instance
Content-Type: application/json

{
  "instance_id": "instance-uuid"
}

Response:

{
  "success": true,
  "message": "Instance destroyed successfully"
}

👥 Admin API - Group Management

List Groups

Retrieve all user groups (requires perm_view_groups).

GET /api/admin/groups

Response:

{
  "success": true,
  "groups": [
    {
      "id": "group-uuid",
      "display_name": "Admin",
      "created_at": "2024-01-15T10:30:00.000000",
      "protected": true,
      "perm_admin_panel": true,
      "perm_view_users": true,
      "perm_edit_users": true,
      "perm_view_droplets": true,
      "perm_edit_droplets": true,
      "perm_view_registry": true,
      "perm_edit_registry": true,
      "perm_view_groups": true,
      "perm_edit_groups": true,
      "perm_view_instances": true,
      "perm_edit_instances": true
    }
  ]
}

Create/Update Group

Add or modify a user group (requires perm_edit_groups).

POST /api/admin/group
Content-Type: application/json

{
  "display_name": "Developer",
  "protected": false,
  "perm_admin_panel": false,
  "perm_view_instances": true,
  "perm_edit_instances": false,
  "perm_view_users": false,
  "perm_edit_users": false,
  "perm_view_droplets": true,
  "perm_edit_droplets": true,
  "perm_view_registry": true,
  "perm_edit_registry": false,
  "perm_view_groups": false,
  "perm_edit_groups": false
}

Response:

{
  "success": true,
  "message": "Group created/updated successfully"
}

Delete Group

Remove a user group (requires perm_edit_groups).

DELETE /api/admin/group
Content-Type: application/json

{
  "group_id": "group-uuid"
}

Response:

{
  "success": true,
  "message": "Group deleted successfully"
}

🗄️ Admin API - Registry Management

List Registries

Retrieve all configured registries (requires perm_view_registry).

GET /api/admin/registry

Response:

{
  "success": true,
  "flowcase_version": "develop",
  "registry": [
    {
      "id": 1,
      "url": "https://registry.flowcase.org",
      "info": {
        "name": "Flowcase Registry",
        "description": "Official Flowcase droplet registry"
      },
      "droplets": [
        {
          "name": "Ubuntu Desktop",
          "image": "ubuntu:20.04-desktop",
          "description": "Ubuntu desktop environment"
        }
      ]
    }
  ]
}

Add/Delete Registry

Manage container registries (requires perm_edit_registry).

POST /api/admin/registry
Content-Type: application/json

{
  "url": "https://registry.company.com"
}
DELETE /api/admin/registry
Content-Type: application/json

{
  "registry_id": 3
}

Response:

{
  "success": true,
  "message": "Registry added/deleted successfully"
}

Get Logs

Retrieve application logs (requires perm_admin_panel).

GET /api/admin/logs?level=ERROR&page=1&per_page=50

Query Parameters:

  • level - Filter by log level (ERROR, WARNING, INFO, DEBUG)
  • page - Page number for pagination
  • per_page - Number of logs per page

Response:

{
  "success": true,
  "logs": [
    {
      "id": 1,
      "level": "ERROR",
      "message": "Failed to connect to Docker daemon",
      "created_at": "2024-01-15T10:30:00.000000"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 250,
    "per_page": 50
  }
}

🔒 Permission Requirements

Permission Matrix

Endpoint Required Permission
/api/droplets User login
/api/instances User login
/api/instance/request User login
/api/instance/{id}/destroy Owner or perm_edit_instances
/api/admin/users perm_view_users
/api/admin/user (POST) perm_edit_users
/api/admin/user (DELETE) perm_edit_users
/api/admin/droplets perm_view_droplets
/api/admin/droplet (POST) perm_edit_droplets
/api/admin/droplet (DELETE) perm_edit_droplets
/api/admin/groups perm_view_groups
/api/admin/group (POST) perm_edit_groups
/api/admin/group (DELETE) perm_edit_groups
/api/admin/instances perm_view_instances
/api/admin/instance (DELETE) perm_edit_instances
/api/admin/registry perm_view_registry / perm_edit_registry
/api/admin/system_info perm_admin_panel
/api/admin/logs perm_admin_panel

📡 WebSocket Endpoints

Instance Connection

Connect to a running droplet instance via WebSocket.

// WebSocket connection for VNC/desktop streaming
const ws = new WebSocket('ws://your-instance/desktop/{instance_id}/vnc/websockify');

// Connection events
ws.onopen = function(event) {
    console.log('Connected to instance');
};

ws.onmessage = function(event) {
    // Handle VNC data
    handleVNCData(event.data);
};

ws.onclose = function(event) {
    console.log('Disconnected from instance');
};

[!INFO] Implementation Note: WebSocket connections are handled by the Guacamole streaming containers, not directly by the Flowcase API. The actual WebSocket endpoint depends on instance configuration.

File Upload WebSocket

Upload files to running instances.

// WebSocket for file uploads
const uploadWs = new WebSocket('ws://your-instance/desktop/{instance_id}/upload');

// Send file data
uploadWs.send(JSON.stringify({
    'action': 'upload',
    'filename': 'document.pdf',
    'data': base64Data
}));

Warning

Planned Feature: Dedicated file upload WebSocket endpoints are planned but not yet implemented. File uploads currently use standard HTTP endpoints through the container's web interface.

🔧 Error Handling

Standard Error Codes

HTTP Code Description Example Response
200 Success {"success": true, "data": {}}
400 Bad Request {"success": false, "error": "Invalid parameters"}
401 Unauthorized {"success": false, "error": "Authentication required"}
403 Forbidden {"success": false, "error": "Permission denied"}
404 Not Found {"success": false, "error": "Resource not found"}
500 Server Error {"success": false, "error": "Internal server error"}

Common Error Responses

Authentication Error:

{
  "success": false,
  "error": "Authentication required",
  "redirect": "/login"
}

Permission Error:

{
  "success": false,
  "error": "Permission denied: perm_edit_users required"
}

Validation Error:

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "username": "Username is required",
    "password": "Password must be at least 8 characters"
  }
}

📝 Usage Examples

Python Example

import requests
import json

# Login
login_data = {
    'username': 'admin',
    'password': 'your_password',
    'remember': 'on'
}

session = requests.Session()
response = session.post('http://flowcase.example.com/login', data=login_data)

if response.json()['success']:
    # Get available droplets
    droplets = session.get('http://flowcase.example.com/api/droplets')
    print(json.dumps(droplets.json(), indent=2))
    
    # Request new instance
    instance_data = {
        'droplet_id': 'droplet-uuid',
        'resolution': '1920x1080'
    }
    
    new_instance = session.post(
        'http://flowcase.example.com/api/instance/request',
        json=instance_data
    )
    
    if new_instance.json()['success']:
        instance_id = new_instance.json()['instance_id']
        print(f"Instance created: {instance_id}")

JavaScript Example

// Login function
async function login(username, password, remember = false) {
    const formData = new FormData();
    formData.append('username', username);
    formData.append('password', password);
    if (remember) formData.append('remember', 'on');
    
    const response = await fetch('/login', {
        method: 'POST',
        body: formData,
        credentials: 'include'
    });
    
    // Login returns a redirect, check if successful
    return response.redirected && response.url.includes('dashboard');
}

// Get droplets function
async function getDroplets() {
    const response = await fetch('/api/droplets', {
        credentials: 'include'
    });
    
    return response.json();
}

// Create instance function
async function createInstance(dropletId, resolution = '1920x1080') {
    const response = await fetch('/api/instance/request', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            droplet_id: dropletId,
            resolution: resolution
        }),
        credentials: 'include'
    });
    
    return response.json();
}

// Usage
(async () => {
    await login('admin', 'password');
    const droplets = await getDroplets();
    
    if (droplets.success && droplets.droplets.length > 0) {
        const instance = await createInstance(droplets.droplets[0].id);
        console.log('Instance created:', instance);
    }
})();

cURL Examples

Login:

curl -X POST http://flowcase.example.com/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'username=admin&password=your_password&remember=on' \
  -c cookies.txt

Get Droplets:

curl -X GET http://flowcase.example.com/api/droplets \
  -b cookies.txt

Create Instance:

curl -X POST http://flowcase.example.com/api/instance/request \
  -H "Content-Type: application/json" \
  -d '{"droplet_id":"droplet-uuid","resolution":"1920x1080"}' \
  -b cookies.txt

Create User (Admin):

curl -X POST http://flowcase.example.com/api/admin/user \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"password","groups":["user-group-uuid"]}' \
  -b cookies.txt

🔄 Rate Limiting

Default Limits

  • Authentication: 5 requests per minute per IP
  • Instance Creation: 10 requests per hour per user
  • General API: 100 requests per minute per user
  • File Upload: 1GB per hour per user

Warning

Planned Feature: Rate limiting is not currently enforced in the API implementation. These limits represent planned functionality for future releases.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642261800

[!INFO] Future Implementation: Rate limit headers will be added when rate limiting is implemented.

📈 Monitoring and Metrics

Health Check Endpoint

GET /health

Response:

{
  "status": "healthy",
  "version": "develop",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "database": "ok",
    "docker": "ok",
    "storage": "ok"
  }
}

Metrics Endpoint (Admin only)

GET /api/admin/metrics

[!INFO] Planned Feature: The metrics endpoint is planned for future releases. Current system information is available through /api/admin/system_info.

Response:

{
  "success": true,
  "metrics": {
    "requests_per_minute": 45,
    "active_sessions": 12,
    "instances_running": 8,
    "cpu_usage": 25.5,
    "memory_usage": 60.2,
    "disk_usage": 45.1
  }
}

📞 API Support

For API-related questions or issues:

  1. Check the Troubleshooting Guide
  2. Review the FAQ
  3. Create an issue on GitHub
  4. Join the developer community discussions

Remember: Always test API calls in a development environment before implementing in production.

Flowcase Wiki

Getting Started

User Documentation

Administration

Technical

Community

External Links

Clone this wiki locally