State Machine API

The state machine exposes a REST API for subscription management, event state, track/zone queries, and replay sessions. Base URL: http://n8n-state-machine:8080 (default)

Health

GET /health

Check if the service is running.

curl http://n8n-state-machine:8080/health

{ "status": "ok" }

Subscriptions

POST /api/subscriptions/

curl -X POST http://n8n-state-machine:8080/api/subscriptions/my-workflow \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "http://n8n:5678/webhook/detections",
    "workflow_name": "obstruction-detection",
    "mode": "streaming",
    "signal_type": "track_state",
    "filters": {
      "datasource_ids": ["507eaeca-cc89-4501-9e0d-0d062a8f355d"],
      "tags": ["forklift", "person"]
    },
    "credentials": {
      "graphql_url": "https://your-instance.worlds.io/graphql",
      "ws_url": "wss://your-instance.worlds.io/graphql",
      "x_token_id": "your-token-id",
      "x_token_value": "your-token-value"
    }
  }'

GET /api/subscriptions

List all active subscriptions.

GET /api/subscriptions/

Get a specific subscription.

DELETE /api/subscriptions/

Remove a subscription. The state machine stops delivering signals for this subscription.

Subscriptions are managed automatically by the trigger nodes. You typically don’t need to call these endpoints directly.

Events (Event Orchestrator)

POST /api/events/

Check or create event state for a scope. Used by the Event Orchestrator node.

curl -X POST http://n8n-state-machine:8080/api/events/track-uuid-here \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "track",
    "workflow_id": "workflow-uuid",
    "workflow_name": "obstruction-detection",
    "conditions_met": true
  }'

PATCH /api/events/

Update event state (e.g., store the global event ID after creation).

Track State

GET /api/tracks/

Query the current state of a track.

curl http://n8n-state-machine:8080/api/tracks/019bb7ea-4050-7e9b-8761-f8df773fd3e5

Returns the full track state object (position, velocity, zones, etc.).

GET /api/tracks/closest-frame

Find the detection frame closest to a given timestamp.

curl "http://n8n-state-machine:8080/api/tracks/closest-frame?track_id=019bb7ea&timestamp=2026-01-13T15:12:52Z"

POST /api/tracks/snapshot

Compute position, velocity, and zone membership for one or more tracks at specific historical timestamps. The endpoint analyzes raw detections within a configurable time window around each requested timestamp.

curl -X POST http://n8n-state-machine:8080/api/tracks/snapshot \
  -H "Content-Type: application/json" \
  -H "x-token-id: your-token-id" \
  -H "x-token-value: your-token-value" \
  -H "x-graphql-url: https://your-instance.worlds.io/graphql" \
  -d '{
    "tracks": [
      {
        "track_id": "019bb7ea-4050-7e9b-8761-f8df773fd3e5",
        "timestamp": "2026-01-13T15:12:52.000Z"
      }
    ],
    "window_seconds": 10
  }'

Request body:

Field	Type	Required	Description
`tracks`	Array	Yes	One or more track queries
`tracks[].track_id`	String	Yes	Track UUID to query
`tracks[].timestamp`	String	Yes	ISO 8601 timestamp to compute the snapshot at
`window_seconds`	Number	No	Seconds before and after the timestamp to include (default: 10)

Headers: x-token-id, x-token-value, and x-graphql-url are required when the track’s detections are not already cached in Redis (DB 3). The endpoint will fall back to the Worlds GraphQL API to fetch detections. Response body:

Field	Type	Description
`snapshots`	Object	Map of track ID to snapshot (null if the track could not be resolved)
`snapshots[].track_id`	String	Track UUID
`snapshots[].tag`	String	Object type tag (e.g., `Person`, `Vehicle`)
`snapshots[].timestamp`	String	The requested timestamp
`snapshots[].window_seconds`	Number	The window used for computation
`snapshots[].detections_in_window`	Number	Number of raw detections found in the window
`snapshots[].position`	Object	Interpolated position at the timestamp
`snapshots[].position.method`	String	`real`, `linear`, `forward_extrapolation`, or `backward_extrapolation`
`snapshots[].position.offset_ms`	Number	Milliseconds between the requested timestamp and the nearest real detection
`snapshots[].position.pix`	Object	Pixel coordinates (`x`, `y`)
`snapshots[].position.geo`	Object	Geographic coordinates (`lon`, `lat`), if available
`snapshots[].position.polygon`	Array	Interpolated bounding box as a 4-point polygon
`snapshots[].motion`	Object	Velocity and direction computed from detections in the window
`snapshots[].motion.pix`	Object	Pixel-space motion (`avg_velocity`, `max_velocity`, `direction`, `sample_count`)
`snapshots[].motion.geo`	Object	Geographic motion (same fields), if available
`snapshots[].zones`	Object	Zone membership at the timestamp
`snapshots[].zones.active_at_timestamp`	Object	Map of zone ID to zone data for zones the track intersected at the timestamp

Zone State

GET /api/zones/

Query the current state of a zone (active tracks, occupancy count).

Replay

POST /api/replay/

Start a replay session for testing.

curl -X POST http://n8n-state-machine:8080/api/replay/test-session \
  -H "Content-Type: application/json" \
  -d '{
    "track_ids": ["019bb7ea-4050-7e9b-8761-f8df773fd3e5"],
    "mode": "auto"
  }'

GET /api/replay/

Get replay session status.

DELETE /api/replay/

Stop and clean up a replay session.

Replay sessions are managed automatically by the Replay Trigger node. These endpoints are documented for debugging purposes.

Getting Started

Concepts

Workflow Guides

Advanced

Health

GET /health

Subscriptions

POST /api/subscriptions/

GET /api/subscriptions

GET /api/subscriptions/

DELETE /api/subscriptions/

Events (Event Orchestrator)

POST /api/events/

PATCH /api/events/

Track State

GET /api/tracks/

GET /api/tracks/closest-frame

POST /api/tracks/snapshot

Zone State

GET /api/zones/

Replay

POST /api/replay/

GET /api/replay/

DELETE /api/replay/

​Health

​GET /health

​Subscriptions

​POST /api/subscriptions/

​GET /api/subscriptions

​GET /api/subscriptions/

​DELETE /api/subscriptions/

​Events (Event Orchestrator)

​POST /api/events/

​PATCH /api/events/

​Track State

​GET /api/tracks/

​GET /api/tracks/closest-frame

​POST /api/tracks/snapshot

​Zone State

​GET /api/zones/

​Replay

​POST /api/replay/

​GET /api/replay/

​DELETE /api/replay/

Health

GET /health

Subscriptions

POST /api/subscriptions/

GET /api/subscriptions

GET /api/subscriptions/

DELETE /api/subscriptions/

Events (Event Orchestrator)

POST /api/events/

PATCH /api/events/

Track State

GET /api/tracks/

GET /api/tracks/closest-frame

POST /api/tracks/snapshot

Zone State

GET /api/zones/

Replay

POST /api/replay/

GET /api/replay/

DELETE /api/replay/