API Reference

Quickstart

You'll need a namespace and bearer token — get one at the pricing section. Once you have your token, you can publish, query, and subscribe immediately.

# Replace YOUR_TOKEN and YOUR_NAMESPACE with your credentials
curl -X POST https://flux-universe.com/api/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "sensors",
    "source": "my-app",
    "timestamp": 1708694400000,
    "payload": {
      "entity_id": "YOUR_NAMESPACE/sensor-01",
      "properties": {
        "temperature": 22.5,
        "status": "active"
      }
    }
  }'

# Reads are open — no token required
curl https://flux-universe.com/api/state/entities/YOUR_NAMESPACE/sensor-01

# Install wscat: npm install -g wscat
wscat -c wss://flux-universe.com/api/ws

# After connecting, send a subscribe message:
{"type": "subscribe", "entity_id": "YOUR_NAMESPACE/sensor-01"}

# Subscribe to everything in your namespace:
{"type": "subscribe", "entity_id": "YOUR_NAMESPACE/*"}

# Or subscribe to all entities (read-only, public):
{"type": "subscribe", "entity_id": "*"}

POST /api/events

Publish a single event. Events are immutable — they update the entity's current state by merging the provided properties.

{
  "stream": "sensors",          // required
  "source": "my-app",            // required
  "timestamp": 1708694400000, // required, Unix epoch ms
  "payload": {                  // required
    "entity_id": "ns/entity-name",
    "properties": {
      "key": "any JSON value"
    }
  },
  "eventId": "optional-uuid"   // optional, auto-generated if omitted
}

{
  "eventId": "01HX...",
  "stream": "sensors"
}

POST /api/events/batch

[
  {
    "stream": "sensors", "source": "agent-01", "timestamp": 1708694400000,
    "payload": { "entity_id": "ns/device-01", "properties": { "temp": 22.1 } }
  },
  {
    "stream": "sensors", "source": "agent-01", "timestamp": 1708694400001,
    "payload": { "entity_id": "ns/device-02", "properties": { "temp": 19.8 } }
  }
]

GET /api/state/entities

List all entities. No authentication required — all reads are public.

# All entities
curl https://flux-universe.com/api/state/entities

# Filter to your namespace
curl "https://flux-universe.com/api/state/entities?prefix=myns/"

[
  {
    "id": "myns/sensor-01",
    "properties": { "temp": 22.5, "status": "active" },
    "lastUpdated": "2026-02-23T10:30:45.123Z"
  }
]

GET /api/state/entities/:id

Fetch the current state of a single entity.

# Fetch a specific entity
curl https://flux-universe.com/api/state/entities/myns/sensor-01

{
  "id": "myns/sensor-01",
  "properties": {
    "temperature": 22.5,
    "status": "active"
  },
  "lastUpdated": "2026-02-23T10:30:45.123Z"
}

DEL /api/state/entities/:id

Delete an entity and all its state. Requires authentication — your namespace token. The entity ID must be within your namespace.

# Delete an entity
curl -X DELETE https://flux-universe.com/api/state/entities/myns/sensor-01 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "entity_id": "myns/sensor-01",
  "eventId": "01HX..."
}

WS /api/ws

Open a persistent WebSocket connection and subscribe to entity state changes. No authentication required — all state changes are publicly observable.

# Subscribe to a specific entity
{ "type": "subscribe", "entity_id": "myns/sensor-01" }

# Subscribe to all entities in a namespace
{ "type": "subscribe", "entity_id": "myns/*" }

# Subscribe to everything
{ "type": "subscribe", "entity_id": "*" }

# Unsubscribe
{ "type": "unsubscribe", "entity_id": "myns/sensor-01" }

# State update (every property change)
{
  "type": "state_update",
  "entity_id": "myns/sensor-01",
  "property": "temperature",
  "value": 22.5,
  "timestamp": "2026-02-23T10:30:45.123Z"
}

# Entity deleted
{
  "type": "entity_deleted",
  "entity_id": "myns/sensor-01",
  "timestamp": "..."
}

# Periodic metrics (sent to all subscribers)
{
  "type": "metrics_update",
  "entities": { "total": 1543 },
  "events": { "total": 458392, "rate_per_second": 45.2 }
}

import asyncio, json
import websockets

async def subscribe():
    url = "wss://flux-universe.com/api/ws"
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({
            "type": "subscribe",
            "entity_id": "myns/*"
        }))
        async for msg in ws:
            event = json.loads(msg)
            if event["type"] == "state_update":
                print(f"{event['entity_id']}.{event['property']} = {event['value']}")

POST /api/namespaces

Register a new namespace. This is handled automatically when you purchase — you'll receive your token via email. The endpoint is documented here for reference.

POST /api/namespaces

{
  "name": "yourname"
}

# Response
{
  "namespaceId": "ns_a3f9b12c",
  "name": "yourname",
  "token": "..."
}

OpenClaw Skill

If you're building with Claude or other OpenClaw-compatible agents, use the official Flux skill — no manual HTTP calls required. The skill provides actions for publishing events, querying entity state, listing entities, batch publishing, and checking connector status.

https://clawhub.ai/EckmanTechLLC/flux

Rate Limits