Resources

API Reference

Query and change a scenario running on SiteCAD Sim, and follow the instance's state

This API is served by a SiteCAD Sim instance. Owners and admins create one for their organization on the Sim Instance page.

Every SiteCAD Sim instance — a non-interactive SiteCAD that keeps one scenario running — serves this API over the scenario it hosts, for agent teams, dashboards and SQL clients. Sim is its own per-instance subscription, separate from the editor plans.

Capabilities

Kit functions over HTTP

Call the instance's kit functions — the toolkit the editor's scripts and assistant use — by name, with their parameters as JSON. A function that writes changes the hosted scenario, which syncs to every editor that has it open.

SQL

Send one SQL statement per request against the hosted scenario. Whether it reads or writes is decided from the statement, and the key must hold the matching scope.

State channel

A WebSocket carrying the instance's integration and device health, connection events, binding and webhook telemetry, and dead letters as they change. It takes the key as ?key= and needs the Live updates scope.

Outbound webhooks

POST to your system when a table changes or a trigger fires, whoever made the change. Failed deliveries are retried with growing waits; ones that run out of retries or overflow the queue are kept as dead letters you can replay or discard from the Integrations page or the admin routes.

Scoped keys

Each key holds some of four scopes, and may be limited to some of the scenario's tables. Every route checks the scope its request needs.

Devices are integrations

Sensors, controllers and vendor clouds connect through the integration layer, set up on the Integrations page, not through this API.

Endpoints

MethodEndpointKeyPurpose
GET/healthNoneLiveness check
GET/versionNoneThe build the instance runs
GET/api/statusReadStatus report: whether the scenario has arrived and the runtime started, the sync state of each database the instance keeps, and its disk use
GET (WebSocket)/api/wsLive updatesState channel: integration and device health, connection events, binding and webhook telemetry, and dead letters as they change; the key goes in ?key=
GET/api/driversReadThe drivers and device templates the instance runs
POST/api/kit/:nameRead or WriteCall a kit function by name; the function decides whether it needs Read or Write
POST/api/sqlRead or WriteRun one SQL statement against the hosted scenario; the statement decides whether it needs Read or Write
POST/api/dead-letter/:id/replayAdministerResend an outbound webhook delivery that ended as a dead letter
POST/api/dead-letter/:id/discardAdministerDrop an outbound webhook delivery that ended as a dead letter
POST/api/archive-exportsReadStart writing an archive file of the hosted scenario at its current state, as the editor writes one, unsigned; body { name, periodEnd?, amends? }
GET/api/archive-exports/:idReadHow an archive export stands: running with its progress, done with the file's name and hash, or failed with the reason
GET/api/archive-exports/:id/fileReadDownload a finished archive file, kept for 24 hours; sign it later in the editor

A keyed request sends Authorization: ApiKey <key>; any other scheme, Bearer included, is refused with 401. Until the instance has received its scenario for the first time, the kit, SQL and dead-letter routes and the start of an archive export answer 503 scenario_not_synced. The Integrations page uses further Administer-scoped routes to commission devices.

Keys and scopes

Read

Query the scenario: read-only SQL, kit functions that only read, the status report, and archive files of the scenario.

Write

Change the scenario: SQL that writes, and kit functions that write or run operations and actions.

Live updates

Open the state channel that streams changes as they happen.

Administer

Manage integration secrets and commissioning, and replay or discard dead letters.

Owners and admins create and revoke keys on the Sim Instance page, choosing the scopes above; a key is shown once, when it is created. A key limited to tables can read them and add rows to them. It cannot change or delete rows, export an archive, open live updates or administer the instance.

Example

Read the scenario's solids over SQL with a key holding Read. The instance's address is on its card on the Sim Instance page.

curl -X POST "https://<instance address>/api/sql" \
  -H "Authorization: ApiKey <key>" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "select id, name from Entity where type = ?", "params": ["s"] }'

{ "ok": true, "kind": "read", "rows": [ { "id": 12, "name": "Pump house" } ] }

Inside the editor, the same SQL runs against the open scenario from the browser DevTools console:

await runSQL("select id, name from Entity where type = 's'");

View Documentation →

Not yet

  • Streams of scenario changes and trigger fires on the WebSocket. To react to a scenario change or a trigger fire today, use an outbound webhook.
  • A signature on outbound webhook calls: a receiver can check the key a subscription sends, but deliveries carry no signature yet.

Explore the Editor

The API reads and changes the same scenario you build in the editor. See it firsthand.