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"
    }
  }'

Zone emit mode (optional, zone state only):

Field	Type	Default	Description
`zone_emit_mode`	String	`"all"`	`"all"` emits `zone_updated` on every detection in an occupied zone. `"composition"` emits only when the subscription’s filtered tag → count composition changes, plus a periodic heartbeat. Composition mode requires `signal_type: "zone_state"` and `mode: "streaming"` — other combinations are rejected with `400`.
`heartbeat_seconds`	Number	`30`	Maximum seconds between emissions for an unchanged composition. Only meaningful when `zone_emit_mode` is `"composition"`. Must be `>= 0`; `0` falls back to the default of 30. Negative values are rejected with `400`.

See Composition emit mode for the full suppression and heartbeat behavior.

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).

Chronicle Queries

POST /api/chronicles/query

Query and aggregate activity or event chronicles over a time range. Used by the Chronicle Aggregation node resource. Pull-style: the endpoint chunks the requested window into ≤24h GraphQL fetches (bounded concurrency 4), dedupes across chunks, then filters and aggregates locally. Credentials are per-request and never persisted. Per-request timeout: 90s.

curl -X POST http://n8n-state-machine:8080/api/chronicles/query \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "graphql_url": "https://your-instance.worlds.io/graphql",
      "token_id": "your-token-id",
      "token_value": "your-token-value"
    },
    "record_kind": "activity_chronicle",
    "start_time": "2026-08-25T00:00:00.000Z",
    "end_time": "2026-08-26T00:00:00.000Z",
    "time_match": "overlap",
    "include_open": true,
    "overlap_lookback_seconds": 604800,
    "filters": {
      "producer_ids": ["producer-uuid"],
      "labels": ["forklift"],
      "statuses": ["active"],
      "priorities": ["high"],
      "site_ids": ["site-uuid"],
      "datasource_ids": ["datasource-uuid"]
    },
    "aggregation": {
      "output": "grouped",
      "group_by": "label"
    },
    "limit": 5000
  }'

Request body:

Field	Type	Required	Description
`credentials.graphql_url`	String	Yes	Worlds GraphQL endpoint. Subject to the `ALLOWED_URL_DOMAINS` SSRF allowlist.
`credentials.token_id` / `credentials.token_value`	String	Yes	`x-token-id` / `x-token-value` auth
`credentials.ws_url`	String	No	Accepted but unused by this endpoint — this is an HTTP-only query, not a subscription.
`record_kind`	String	Yes	`activity_chronicle` (has `start_time`/`end_time`, `sites`, `dataSources`) or `event_chronicle` (point-in-time: only `timestamp`)
`start_time` / `end_time`	String (ISO 8601)	Yes	Query window
`time_match`	String	No	`started_in` (default) — chronicle’s start falls within `[start_time, end_time)`; or `overlap` — chronicle’s `[start, end]` interval overlaps `[start_time, end_time)`, with an open chronicle treated as extending to now (producers that never close chronicles will match their full backlog in any window)
`include_open`	Boolean	No	Default `true`. When `false`, excludes chronicles with no `end_time`. Only meaningful for activity chronicles.
`overlap_lookback_seconds`	Number	No	Only used when `time_match: "overlap"`. Extends the fetch window backward by this many seconds before `start_time` so chronicles that started earlier but still overlap are found. Default `604800` (7 days, mirrors `CHRONICLE_STATE_TTL`’s default).
`filters.producer_ids` / `labels` / `statuses` / `priorities` / `site_ids` / `datasource_ids`	Array	No	OR within a field, AND across fields (same semantics as subscription filters). Applied locally after fetching — the only server-side (GraphQL) filtering is the time-range chunking.
`aggregation.output`	String	No	`raw` (default, returns `chronicles`), `rollup` (returns `rollup`), `grouped` (returns `groups`, requires `group_by`), or `raw_and_rollup` (returns both `chronicles` and `rollup`)
`aggregation.group_by`	String	Required when `output: "grouped"`	One of `label`, `status`, `priority`, `producer`, `site`. Multi-valued dimensions (`label`, `site`) fan a chronicle into every matching group; no value for the dimension falls into a group keyed `"(none)"`.
`limit`	Number	No	Default `5000`, max `20000`. Applied to the matched set (sorted by start time) after filtering.

The total fetch span (end_time - start_time, plus overlap_lookback_seconds when time_match: "overlap") is capped at 100 24h chunks. Requests exceeding it are rejected with a 400 — narrow the window or reduce the lookback.

record_kind: "event_chronicle" maps each chronicle internally to a zero-length interval (start = end = timestamp) so window matching and aggregation work uniformly. This means include_open is a no-op for event chronicles (they’re always closed), and site_ids/datasource_ids filters never match them (event chronicles carry no site/data-source data). An event chronicle’s producer is still a chronicle producer, so producer_ids applies normally.

Response body (aggregation.output: "grouped" shown; raw returns chronicles instead of groups, raw_and_rollup returns both chronicles and rollup):

{
  "groups": [
    {
      "key": "forklift",
      "count": 12,
      "chronicles": [ { "...": "raw chronicle object, timestamps normalized to ISO 8601 UTC" } ]
    },
    {
      "key": "(none)",
      "count": 3,
      "chronicles": [ { "...": "chronicles with no value for the group_by dimension" } ]
    }
  ],
  "meta": {
    "window": { "start_time": "2026-08-25T00:00:00.000Z", "end_time": "2026-08-26T00:00:00.000Z", "time_match": "overlap" },
    "record_kind": "activity_chronicle",
    "chunks_queried": 1,
    "total_matched": 15,
    "truncated": false
  }
}

aggregation.output: "rollup" (or raw_and_rollup, alongside chronicles) returns a rollup summary instead of groups:

{
  "rollup": {
    "total": 15,
    "by_status": { "active": 10, "closed": 5 },
    "by_priority": { "high": 4, "medium": 11 },
    "by_label": { "forklift": 12, "pedestrian": 3 },
    "by_producer": { "producer-uuid": 15 },
    "earliest_start": "2026-08-25T14:03:00.000Z",
    "latest_end": "2026-08-25T23:58:00.000Z"
  },
  "meta": { "...": "same shape as above" }
}

earliest_start/latest_end are omitted when the retained set is empty. latest_end only advances for chronicles with a known end_time (open chronicles don’t contribute).

Field	Type	Description
`meta.total_matched`	Number	The retained (post-truncation) count
`meta.truncated`	Boolean	`true` when the match count exceeded `limit`. `rollup`/`groups` are computed over the retained set, not the full match set.
`meta.chunks_queried`	Number	Number of ≤24h GraphQL chunks the window was split into

Errors: 400 on validation failure (bad JSON, missing/invalid fields), 502 on upstream GraphQL failure (error text surfaced in the response body), 503 if the handler isn’t wired for this deployment, 405 on non-POST.

This endpoint ships with the state machine, not with the n8n nodes package. If the Chronicle Aggregation node reports a state machine version error, upgrade n8n-state-machine before upgrading worlds-n8n-nodes — an older state machine without this endpoint returns 404, which the node surfaces as a clear “upgrade n8n-state-machine” message rather than a generic failure.

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

Guides

Trigger Nodes

Check Nodes

Event Nodes

Action Nodes

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/

Chronicle Queries

POST /api/chronicles/query

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/

​Chronicle Queries

​POST /api/chronicles/query

​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/

Chronicle Queries

POST /api/chronicles/query

Replay

POST /api/replay/

GET /api/replay/

DELETE /api/replay/