Overview

The EdgeFlow Cloud API provides a comprehensive REST interface for managing devices, flows, deployments, billing, and more. All endpoints use JSON request/response bodies and require JWT Bearer token authentication unless otherwise noted.

Base URL

https://saas.edgx.cloud/api/v1

Authentication

# JWT Bearer Token (primary)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API Key (programmatic access)
X-API-Key: edgeflow_abcdef...

Middleware

Middleware	Description
Rate Limiting	IP-based rate limiting on all routes. Per-user and per-org limits available.
Authentication	JWT validation via `Authorization: Bearer` header
Tenant Isolation	Ensures all queries are scoped to the user's organization

Authentication

Method	Endpoint	Auth	Description
`POST`	`/auth/register`	None	Register new user and organization
`POST`	`/auth/login`	None	Login with email/password, returns JWT
`POST`	`/auth/refresh`	None	Refresh expired access token
`POST`	`/auth/logout`	JWT	Invalidate session
`GET`	`/auth/profile`	JWT	Get current user profile
`PUT`	`/auth/profile`	JWT	Update user profile
`POST`	`/auth/change-password`	JWT	Change user password

Devices

Method	Endpoint	Description
`GET`	`/devices`	List all devices (supports `limit`, `offset`, `status` filters)
`POST`	`/devices`	Create/register a new device
`GET`	`/devices/:id`	Get device details
`PUT`	`/devices/:id`	Update device metadata and tags
`DELETE`	`/devices/:id`	Delete device
`GET`	`/devices/:id/status`	Get real-time device status
`GET`	`/devices/:id/shadow`	Get device shadow state
`PUT`	`/devices/:id/shadow`	Update desired shadow state

Edge Node Remote Management

Proxy commands to edge devices through the WebSocket tunnel:

Method	Endpoint	Description
`GET`	`/edge-nodes/:deviceId/health`	Check edge node health
`GET`	`/edge-nodes/:deviceId/node-types`	Get available node types
`GET`	`/edge-nodes/:deviceId/editor-url`	Get remote editor proxy URL
`GET`	`/edge-nodes/:deviceId/flows`	List flows on edge device
`GET`	`/edge-nodes/:deviceId/flows/:flowId`	Get flow from edge device
`POST`	`/edge-nodes/:deviceId/flows`	Create flow on edge device
`PUT`	`/edge-nodes/:deviceId/flows/:flowId`	Update flow on edge device
`DELETE`	`/edge-nodes/:deviceId/flows/:flowId`	Delete flow from edge device
`POST`	`/edge-nodes/:deviceId/flows/:flowId/start`	Start flow on edge device
`POST`	`/edge-nodes/:deviceId/flows/:flowId/stop`	Stop flow on edge device
`PUT`	`/edge-nodes/:deviceId/configure`	Update edge device connection settings

Organizations

Method	Endpoint	Description
`GET`	`/organizations`	List user's organizations
`GET`	`/organizations/:id`	Get organization details
`PUT`	`/organizations/:id`	Update organization settings

Flows

Method	Endpoint	Description
`GET`	`/flows`	List all cloud flows
`POST`	`/flows`	Create a new flow
`GET`	`/flows/:id`	Get flow details
`PUT`	`/flows/:id`	Update flow definition
`DELETE`	`/flows/:id`	Delete flow
`POST`	`/flows/:id/publish`	Publish flow for deployment

Deployments

Method	Endpoint	Description
`GET`	`/deployments`	List all deployments
`POST`	`/deployments`	Create deployment
`GET`	`/deployments/:id`	Get deployment status
`POST`	`/deployments/:id/start`	Start deployment
`POST`	`/deployments/:id/pause`	Pause deployment
`POST`	`/deployments/:id/rollback`	Rollback deployment

Billing

Method	Endpoint	Description
`GET`	`/billing/plans`	List available subscription plans
`GET`	`/billing/subscription`	Get current subscription
`POST`	`/billing/subscription`	Create subscription
`PUT`	`/billing/subscription`	Change subscription plan
`DELETE`	`/billing/subscription`	Cancel subscription
`POST`	`/billing/subscription/resume`	Resume canceled subscription
`GET`	`/billing/usage`	Get usage summary
`GET`	`/billing/quotas`	Get current quota limits
`GET`	`/billing/invoices`	List invoices
`GET`	`/billing/invoices/:id`	Get invoice details
`GET`	`/billing/invoices/:id/download`	Download invoice PDF
`POST`	`/billing/payment-methods`	Add payment method
`GET`	`/billing/payment-methods`	List payment methods
`DELETE`	`/billing/payment-methods/:id`	Remove payment method
`POST`	`/billing/webhooks/stripe`	Stripe webhook handler

Metrics & Logs

Method	Endpoint	Description
`GET`	`/metrics`	Query organization-wide metrics
`GET`	`/metrics/devices/:id`	Get device-specific metrics
`GET`	`/logs`	Query organization logs
`GET`	`/logs/devices/:id`	Get device-specific logs

Alerts

Method	Endpoint	Description
`GET`	`/alerts`	List alert rules
`POST`	`/alerts`	Create alert rule
`GET`	`/alerts/:id`	Get alert details
`PUT`	`/alerts/:id`	Update alert rule
`DELETE`	`/alerts/:id`	Delete alert rule
`POST`	`/alerts/:id/acknowledge`	Acknowledge firing alert

Tunnel

Method	Endpoint	Auth	Description
`GET`	`/tunnel`	WebSocket	Device WebSocket tunnel (handshake auth)
`GET`	`/tunnel/status`	JWT	Get tunnel connection status

Error Responses

All endpoints return consistent error responses:

{
  "error": "flow not found",
  "code": "NOT_FOUND",
  "status": 404
}

Status Code	Description
`400`	Bad Request — Invalid parameters or body
`401`	Unauthorized — Missing or invalid token
`403`	Forbidden — Insufficient permissions or wrong organization
`404`	Not Found — Resource does not exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error

Rate Limiting

Scope	Description
IP-based	Default for all routes, prevents abuse from single IPs
Per-User	Applied to sensitive operations (auth, profile)
Per-Organization	Higher limits (10x) for organization-scoped resources