Skip to main content

API Reference

Complete API reference for Nekzus. All endpoints are documented with request/response formats, authentication requirements, and example usage.

Overview​

Nekzus provides a RESTful API for managing services, devices, containers, and system configuration. The API follows standard HTTP conventions and returns JSON responses.

Base URL​

https://localhost:8443/api/v1    # HTTPS (recommended)
http://localhost:8080/api/v1     # HTTP (development only, requires --insecure-http flag)

API Version​

All responses include an X-API-Version header indicating the current API version.

Content Type​

All requests and responses use application/json unless otherwise specified.

Authentication​

Nekzus supports multiple authentication methods depending on the use case.

Authentication Methods​

MethodUse CaseHeader Format
JWT TokenMobile apps, external clientsAuthorization: Bearer <jwt-token>
Bootstrap TokenInitial device pairingAuthorization: Bearer <bootstrap-token>
API KeyExternal integrations, CI/CDX-API-Key: nekzus_<64-char-hex>
IP-BasedLocal network requestsNo header required for localhost

JWT Tokens​

JWT tokens are obtained through the device pairing flow and are valid for 12 hours.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Token Refresh

Use the /api/v1/auth/refresh endpoint to obtain a new token before expiration. The refresh endpoint accepts both valid and recently expired tokens.

Bootstrap Tokens​

Short-lived tokens (5 minutes) used only for initial device pairing. Obtained from QR code scanning.

API Keys​

Permanent tokens for external integrations. Format: nekzus_<64-character-hex-string>

X-API-Key: nekzus_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
API Key Security

The full API key is only shown once at creation. Store it securely as it cannot be retrieved again.

Permission Scopes​

ScopeDescription
read:catalogRead app catalog and routes
read:eventsSubscribe to real-time events
read:*All read permissions
write:*All write permissions
access:adminAdministrative access

Rate Limiting​

All endpoints are rate-limited per IP address. Exceeding limits returns 429 Too Many Requests.

Endpoint CategoryRate LimitBurst
Health checks10 req/sec50
Authentication10 req/min10
QR code generation1 req/sec5
WebSocket connections6 req/min3
Device management30 req/min30
Container operations30 req/min20
General API30 req/min30

Rate limit headers are included in responses:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1736949720

Error Handling​

All errors return a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Error Codes​

CodeHTTP StatusDescription
UNAUTHORIZED401Authentication required
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
METHOD_NOT_ALLOWED405HTTP method not supported
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error
STORAGE_UNAVAILABLE503Storage service unavailable

Health Endpoints​

Health check endpoints for monitoring and orchestration. No authentication required.

GET /healthz​

Returns detailed health status.

curl https://localhost:8443/healthz

GET /livez​

Kubernetes liveness probe. Returns 200 if the process is alive.

curl https://localhost:8443/livez

GET /readyz​

Kubernetes readiness probe. Returns 200 if ready to serve traffic.

curl https://localhost:8443/readyz

Authentication Endpoints​

GET /api/v1/auth/qr​

Generates a QR code for mobile app pairing. The QR code contains a minimal payload with the base URL and a short pairing code. The mobile app uses this code to retrieve the full pairing configuration via GET /api/v1/pair/{code}.

Authentication: None Rate Limit: 1 req/sec, burst 5

ParameterTypeDescription
formatqueryResponse format: json (default) or png
curl https://localhost:8443/api/v1/auth/qr
QR Code Contents

The QR code encodes a minimal JSON payload:

  • u: Base URL of the Nekzus instance
  • c: Short pairing code (8 characters, valid for 5 minutes)

The code field is also returned separately for manual entry when QR scanning is not possible.

POST /api/v1/pair​

Redeems a pairing code and returns the full pairing configuration. This is the second step of the v2 pairing flow after scanning the QR code.

Authentication: None Rate Limit: 10 req/min (per-IP) + global rate limiting Required Header: X-Pairing-Request: true

ParameterTypeDescription
codebody8-character pairing code from QR scan
curl -X POST https://localhost:8443/api/v1/pair \
  -H "Content-Type: application/json" \
  -H "X-Pairing-Request: true" \
  -d '{"code": "ABCD1234"}'
Security Features
  • Single Use: Codes are invalidated after first successful redemption
  • 5-Minute Expiry: Codes expire 5 minutes after generation
  • Rate Limiting: Both per-IP and global rate limits are enforced
  • Code Locking: Codes are locked after 5 failed redemption attempts
  • Required Header: The X-Pairing-Request: true header prevents CSRF attacks

POST /api/v1/auth/pair​

Pairs a new device using a bootstrap token from QR code.

Authentication: Bootstrap token Rate Limit: 10 req/min

curl -X POST https://localhost:8443/api/v1/auth/pair \
  -H "Authorization: Bearer bootstrap_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "device": {
      "id": "my-iphone-123",
      "model": "iPhone 15 Pro",
      "platform": "ios",
      "pushToken": "apns_token_xyz"
    }
  }'

Supported Platforms: ios, android, web, desktop, linux, macos, windows

POST /api/v1/auth/refresh​

Refreshes an existing JWT token.

Authentication: JWT token (can be expired) Rate Limit: 10 req/min

curl -X POST https://localhost:8443/api/v1/auth/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

GET /api/v1/auth/setup-status​

Checks if initial setup is required (no users exist).

Authentication: None

curl https://localhost:8443/api/v1/auth/setup-status

POST /api/v1/auth/setup​

Creates the first admin user. Only works if no users exist.

Authentication: None

curl -X POST https://localhost:8443/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure-password-here"
  }'

POST /api/v1/auth/login​

Authenticates a user with username and password.

Authentication: None

curl -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure-password-here"
  }'

GET /api/v1/auth/me​

Returns the current authenticated user's information.

Authentication: JWT token

curl https://localhost:8443/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/v1/auth/logout​

Logs out the current user. Currently client-side only (discards token).

Authentication: JWT token

curl -X POST https://localhost:8443/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Admin Endpoints​

GET /api/v1/admin/info​

Returns Nekzus instance information.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/admin/info

GET /api/v1/stats​

Returns aggregated system statistics.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/stats

GET /api/v1/activity/recent​

Returns recent activity events.

Authentication: IP-based (local) or JWT

ParameterTypeDefaultDescription
limitquery50Maximum events to return
offsetquery0Number of events to skip
curl "https://localhost:8443/api/v1/activity/recent?limit=10"

GET /api/v1/audit-logs​

Returns audit logs with optional filtering.

Authentication: JWT token (strict)

ParameterTypeDescription
actionqueryFilter by action type
actorqueryFilter by actor (device/user ID)
limitqueryMaximum logs to return (default: 100, max: 1000)
offsetqueryNumber of logs to skip
curl "https://localhost:8443/api/v1/audit-logs?limit=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Apps and Routes​

GET /api/v1/apps​

Returns all registered applications with health status.

Authentication: IP-based (local) or JWT with read:catalog scope

curl https://localhost:8443/api/v1/apps

GET /api/v1/apps/{appId}/favicon​

Returns the favicon for an application.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/apps/grafana/favicon -o favicon.ico

GET /api/v1/routes​

Returns all registered proxy routes.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/routes

PUT /api/v1/routes/{routeId}​

Updates an existing route.

Authentication: IP-based (local) or JWT with write:* scope

curl -X PUT https://localhost:8443/api/v1/routes/route_grafana \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "route_grafana",
    "appId": "grafana",
    "pathBase": "/apps/grafana/",
    "to": "http://grafana:3000",
    "websocket": true,
    "icon": "chart-line"
  }'

DELETE /api/v1/routes/{routeId}​

Deletes a route.

Authentication: IP-based (local) or JWT with write:* scope

curl -X DELETE https://localhost:8443/api/v1/routes/route_grafana

Discovery​

GET /api/v1/discovery/proposals​

Returns pending service discovery proposals.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/discovery/proposals

POST /api/v1/discovery/proposals/{proposalId}/approve​

Approves a discovery proposal, adding it to the catalog.

Authentication: IP-based (local) or JWT with write:* scope

curl -X POST https://localhost:8443/api/v1/discovery/proposals/proposal_abc123/approve \
  -H "Content-Type: application/json" \
  -d '{"port": 3000}'

POST /api/v1/discovery/proposals/{proposalId}/dismiss​

Dismisses a discovery proposal.

Authentication: IP-based (local) or JWT with write:* scope

curl -X POST https://localhost:8443/api/v1/discovery/proposals/proposal_abc123/dismiss

POST /api/v1/discovery/rediscover​

Triggers a fresh discovery scan by clearing dismissed proposals.

Authentication: IP-based (local) or JWT

curl -X POST https://localhost:8443/api/v1/discovery/rediscover

Devices​

GET /api/v1/devices​

Returns all paired devices.

Authentication: IP-based (local) or JWT

ParameterTypeDefaultDescription
limitquery-1Maximum devices to return (-1 = no limit)
offsetquery0Number of devices to skip
curl https://localhost:8443/api/v1/devices

GET /api/v1/devices/{deviceId}​

Returns details for a specific device.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/devices/dev-a1b2c3d4

PATCH /api/v1/devices/{deviceId}​

Updates device metadata.

Authentication: IP-based (local) or JWT

curl -X PATCH https://localhost:8443/api/v1/devices/dev-a1b2c3d4 \
  -H "Content-Type: application/json" \
  -d '{"deviceName": "John'\''s New iPhone"}'

DELETE /api/v1/devices/{deviceId}​

Revokes device access. All existing tokens become invalid.

Authentication: IP-based (local) or JWT

curl -X DELETE https://localhost:8443/api/v1/devices/dev-a1b2c3d4

API Keys​

GET /api/v1/apikeys​

Returns all API keys (without the actual key values).

Authentication: IP-based (local) or JWT with access:admin scope

curl https://localhost:8443/api/v1/apikeys

POST /api/v1/apikeys​

Creates a new API key.

Authentication: IP-based (local) or JWT with access:admin scope

One-Time Display

The full API key is only returned once at creation. Store it securely.

curl -X POST https://localhost:8443/api/v1/apikeys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CI/CD Pipeline",
    "scopes": ["read:catalog", "read:events"],
    "expiresAt": "2026-01-15T00:00:00Z"
  }'

GET /api/v1/apikeys/{keyId}​

Returns details for a specific API key.

Authentication: IP-based (local) or JWT with access:admin scope

curl https://localhost:8443/api/v1/apikeys/key_abc123def456

DELETE /api/v1/apikeys/{keyId}​

Revokes or permanently deletes an API key.

Authentication: IP-based (local) or JWT with access:admin scope

ParameterTypeDefaultDescription
permanentqueryfalsePermanently delete the key
curl -X DELETE https://localhost:8443/api/v1/apikeys/key_abc123def456

Containers​

Container management endpoints require Docker integration to be enabled.

Runtime Support

Nekzus supports both Docker and Kubernetes runtimes. Use the runtime query parameter to specify the target runtime.

GET /api/v1/containers​

Lists all containers from configured runtimes.

Authentication: IP-based (local) or JWT

ParameterTypeDescription
runtimequeryFilter by runtime: docker or kubernetes
namespacequeryKubernetes namespace filter
curl https://localhost:8443/api/v1/containers

GET /api/v1/containers/{containerId}​

Returns detailed information about a container.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/containers/abc123def456

POST /api/v1/containers/{containerId}/start​

Starts a container asynchronously. Returns 202 Accepted immediately.

Authentication: IP-based (local) or JWT with write:* scope

curl -X POST https://localhost:8443/api/v1/containers/abc123def456/start

WebSocket Notification:

{
  "type": "container.start.completed",
  "data": {
    "containerId": "abc123def456",
    "status": "started",
    "message": "Container started successfully",
    "timestamp": 1701388801
  }
}

POST /api/v1/containers/{containerId}/stop​

Stops a container asynchronously.

Authentication: IP-based (local) or JWT with write:* scope

ParameterTypeDefaultDescription
timeoutquery10Grace period in seconds (1-300)
curl -X POST "https://localhost:8443/api/v1/containers/abc123def456/stop?timeout=30"

POST /api/v1/containers/{containerId}/restart​

Restarts a container asynchronously.

Authentication: IP-based (local) or JWT with write:* scope

ParameterTypeDefaultDescription
timeoutquery10Grace period in seconds (1-300)
curl -X POST https://localhost:8443/api/v1/containers/abc123def456/restart

GET /api/v1/containers/{containerId}/stats​

Returns resource usage statistics for a container.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/containers/abc123def456/stats

GET /api/v1/containers/stats​

Returns stats for all running containers.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/containers/stats

Bulk Operations​

POST /api/v1/containers/start-all​

Starts all stopped containers.

POST /api/v1/containers/stop-all​

Stops all running containers.

POST /api/v1/containers/restart-all​

Restarts all containers.

POST /api/v1/containers/batch​

Performs operations on multiple containers.

curl -X POST https://localhost:8443/api/v1/containers/batch \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "restart",
    "containerIds": ["abc123", "def456", "ghi789"]
  }'

Toolbox​

One-click Docker Compose service deployment.

GET /api/v1/toolbox/services​

Lists all available services in the toolbox catalog.

Authentication: IP-based (local) or JWT

ParameterTypeDescription
categoryqueryFilter by category
curl https://localhost:8443/api/v1/toolbox/services

GET /api/v1/toolbox/services/{id}​

Returns details for a specific service template.

Authentication: IP-based (local) or JWT

POST /api/v1/toolbox/deploy​

Deploys a service from the toolbox.

Authentication: IP-based (local) or JWT

curl -X POST https://localhost:8443/api/v1/toolbox/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "portainer",
    "serviceName": "my-portainer",
    "envVars": {
      "ADMIN_PASSWORD": "secure-password"
    },
    "customPort": 9000,
    "autoStart": true
  }'

GET /api/v1/toolbox/deployments​

Lists all deployments.

Authentication: IP-based (local) or JWT

ParameterTypeDescription
statusqueryFilter by status

GET /api/v1/toolbox/deployments/{id}​

Returns deployment status.

Authentication: IP-based (local) or JWT

DELETE /api/v1/toolbox/deployments/{id}​

Removes a deployment.

Authentication: IP-based (local) or JWT

ParameterTypeDefaultDescription
removeVolumesqueryfalseAlso remove associated volumes

Scripts​

Script execution and workflow automation.

GET /api/v1/scripts​

Lists all registered scripts.

Authentication: IP-based (local) or JWT

ParameterTypeDescription
categoryqueryFilter by category

GET /api/v1/scripts/available​

Lists scripts found in the scripts directory that haven't been registered.

Authentication: IP-based (local) or JWT

POST /api/v1/scripts​

Registers a new script.

Authentication: IP-based (local) or JWT

curl -X POST https://localhost:8443/api/v1/scripts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup Database",
    "description": "Creates a database backup",
    "category": "maintenance",
    "scriptPath": "/scripts/backup-db.sh",
    "timeoutSeconds": 300,
    "parameters": [
      {
        "name": "output_dir",
        "type": "string",
        "required": true,
        "default": "/backups"
      }
    ]
  }'

GET /api/v1/scripts/{id}​

Returns script details.

PUT /api/v1/scripts/{id}​

Updates a script.

DELETE /api/v1/scripts/{id}​

Deletes a script.

POST /api/v1/scripts/{id}/execute​

Executes a script.

Authentication: IP-based (local) or JWT

curl -X POST https://localhost:8443/api/v1/scripts/backup-database/execute \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "output_dir": "/backups/daily"
    },
    "dryRun": false
  }'

POST /api/v1/scripts/{id}/dry-run​

Executes a script in dry-run mode.

GET /api/v1/executions​

Lists script executions.

ParameterTypeDescription
scriptIdqueryFilter by script ID
statusqueryFilter by status
limitqueryMaximum results (default: 50, max: 100)
offsetquerySkip results

GET /api/v1/executions/{id}​

Returns execution details.

Workflows​

GET /api/v1/workflows​

Lists all workflows.

POST /api/v1/workflows​

Creates a workflow.

GET /api/v1/workflows/{id}​

Returns workflow details.

DELETE /api/v1/workflows/{id}​

Deletes a workflow.

Schedules​

GET /api/v1/schedules​

Lists all schedules.

POST /api/v1/schedules​

Creates a schedule.

curl -X POST https://localhost:8443/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "scriptId": "backup-database",
    "cronExpression": "0 2 * * *",
    "parameters": {"output_dir": "/backups/nightly"},
    "enabled": true
  }'

GET /api/v1/schedules/{id}​

Returns schedule details.

DELETE /api/v1/schedules/{id}​

Deletes a schedule.

Certificates​

TLS certificate management.

POST /api/v1/certificates/generate​

Generates a new self-signed certificate.

Authentication: JWT token

curl -X POST https://localhost:8443/api/v1/certificates/generate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["localhost", "192.168.1.100", "nekzus.local"],
    "provider": "self-signed"
  }'

GET /api/v1/certificates​

Lists all certificates.

Authentication: JWT token

{
  "certificates": [
    {
      "domain": "localhost",
      "issuer": "Nekzus Self-Signed CA",
      "not_before": "2025-01-15T00:00:00Z",
      "not_after": "2026-01-15T00:00:00Z",
      "sans": ["localhost", "192.168.1.100"],
      "fingerprint": "SHA256:abc123...",
      "expires_in_days": 365
    }
  ],
  "count": 1
}

GET /api/v1/certificates/suggest​

Suggests domains for certificate generation based on local network.

Authentication: JWT token

{
  "suggestions": ["localhost", "macbook-pro.local", "192.168.1.100"],
  "count": 3
}

GET /api/v1/certificates/{domain}​

Returns certificate details for a domain.

DELETE /api/v1/certificates/{domain}​

Deletes a certificate.

Backups​

Backup and disaster recovery.

GET /api/v1/backups​

Lists all backups.

Authentication: IP-based (local) or JWT

POST /api/v1/backups​

Creates a new backup.

Authentication: IP-based (local) or JWT

curl -X POST https://localhost:8443/api/v1/backups \
  -H "Content-Type: application/json" \
  -d '{"description": "Pre-upgrade backup"}'

GET /api/v1/backups/{id}​

Returns backup details.

DELETE /api/v1/backups/{id}​

Deletes a backup.

POST /api/v1/backups/{id}/restore​

Restores from a backup.

curl -X POST https://localhost:8443/api/v1/backups/backup_123/restore \
  -H "Content-Type: application/json" \
  -d '{
    "restoreApps": true,
    "restoreRoutes": true,
    "restoreDevices": false
  }'

GET /api/v1/backups/scheduler/status​

Returns backup scheduler status.

POST /api/v1/backups/scheduler/trigger​

Triggers a scheduled backup manually.

System​

GET /api/v1/system/resources​

Returns system resource usage (CPU, RAM, disk).

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/system/resources

GET /api/v1/stats/quick​

Returns quick stats optimized for mobile/widgets.

Authentication: JWT token (strict)

GET /api/v1/services/{appId}/health​

Returns health status for a specific service.

Authentication: IP-based (local) or JWT

curl https://localhost:8443/api/v1/services/grafana/health

Webhooks​

External notification endpoints.

POST /api/v1/webhooks/activity​

Creates an activity event via webhook.

Authentication: API key or JWT

curl -X POST https://localhost:8443/api/v1/webhooks/activity \
  -H "X-API-Key: nekzus_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Deployment completed",
    "icon": "CheckCircle",
    "iconClass": "success",
    "details": "Version 2.0.0 deployed successfully",
    "deviceIds": ["dev-a1b2c3d4"]
  }'

POST /api/v1/webhooks/notify​

Sends an arbitrary notification via WebSocket.

Authentication: API key or JWT

curl -X POST https://localhost:8443/api/v1/webhooks/notify \
  -H "X-API-Key: nekzus_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom_event",
    "data": {
      "title": "Build Complete",
      "status": "success"
    },
    "deviceIds": []
  }'

Federation​

Peer-to-peer federation for multi-Nexus deployments.

GET /api/v1/federation/peers​

Lists all federation peers.

Authentication: IP-based (local) or JWT

GET /api/v1/federation/peers/{id}​

Returns peer details.

DELETE /api/v1/federation/peers/{id}​

Removes a peer from the federation.

POST /api/v1/federation/sync​

Triggers a catalog sync with all peers.

GET /api/v1/federation/status​

Returns federation status and health.

{
  "enabled": true,
  "local_peer_id": "peer_abc123",
  "local_peer_name": "nekzus-primary",
  "peer_count": 3,
  "peers_by_status": {
    "connected": 2,
    "disconnected": 1
  },
  "running": true
}

WebSocket​

Real-time bidirectional communication.

GET /api/v1/ws​

Establishes a WebSocket connection for real-time updates.

Rate Limit: 6 req/min, burst 3

Connection Flow​

  1. Client connects to /api/v1/ws
  2. Client sends auth message with JWT token
  3. Server responds with auth_success or auth_failed
  4. Server sends hello message with connection info
  5. Bidirectional messaging with ping/pong keepalive

Authentication Message​

{
  "type": "auth",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Message Types​

TypeDirectionDescription
authClient -> ServerAuthentication request
auth_successServer -> ClientAuthentication succeeded
auth_failedServer -> ClientAuthentication failed
helloServer -> ClientConnection established
ping / pongBidirectionalKeepalive
discoveryServer -> ClientService discovery event
config_reloadServer -> ClientConfiguration changed
device_pairedServer -> ClientNew device paired
device_revokedServer -> ClientDevice access revoked
health_changeServer -> ClientService health changed
webhookServer -> ClientWebhook notification
container.start.completedServer -> ClientContainer started
container.stop.completedServer -> ClientContainer stopped
container.restart.completedServer -> ClientContainer restarted
container.logs.dataServer -> ClientContainer log data
notification_ackClient -> ServerNotification acknowledged

Example: Subscribe to Container Logs​

{
  "type": "container.logs.subscribe",
  "data": {
    "containerId": "abc123def456",
    "tail": 100,
    "follow": true,
    "timestamps": true
  }
}

Metrics​

GET /metrics​

Prometheus metrics endpoint.

Authentication: None Rate Limit: 30 req/min

Returns Prometheus-formatted metrics for monitoring.

curl https://localhost:8443/metrics

Reverse Proxy​

/apps/{appId}/*​

Proxies requests to registered applications.

Authentication: IP-based (local) or JWT (configurable per route)

The proxy supports:

  • HTTP/HTTPS proxying
  • WebSocket upgrades (when enabled on route)
  • Server-Sent Events (SSE)
  • Path prefix stripping
  • Header forwarding
  • Response caching (configurable)

Example:

# Access Grafana through the proxy
curl https://localhost:8443/apps/grafana/

Session Cookies​

Mobile webview session persistence.

GET /api/v1/session-cookies​

Lists stored session summaries (no cookie values).

Authentication: JWT token (strict)

DELETE /api/v1/session-cookies​

Clears all sessions for the device.

DELETE /api/v1/session-cookies/{appId}​

Clears sessions for a specific app.

Export​

Container configuration export for migration.

GET /api/v1/containers/{containerId}/export/preview​

Previews export configuration.

Authentication: IP-based (local) or JWT

POST /api/v1/containers/{containerId}/export​

Exports container configuration.

Authentication: IP-based (local) or JWT

POST /api/v1/containers/batch/export/preview​

Previews batch export configuration.

POST /api/v1/containers/batch/export​

Exports multiple container configurations.