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
| Method | Endpoint | Key | Purpose |
|---|---|---|---|
| GET | /health | None | Liveness check |
| GET | /version | None | The build the instance runs |
| GET | /api/status | Read | Status 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/ws | Live updates | State channel: integration and device health, connection events, binding and webhook telemetry, and dead letters as they change; the key goes in ?key= |
| GET | /api/drivers | Read | The drivers and device templates the instance runs |
| POST | /api/kit/:name | Read or Write | Call a kit function by name; the function decides whether it needs Read or Write |
| POST | /api/sql | Read or Write | Run one SQL statement against the hosted scenario; the statement decides whether it needs Read or Write |
| POST | /api/dead-letter/:id/replay | Administer | Resend an outbound webhook delivery that ended as a dead letter |
| POST | /api/dead-letter/:id/discard | Administer | Drop an outbound webhook delivery that ended as a dead letter |
| POST | /api/archive-exports | Read | Start 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/:id | Read | How 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/file | Read | Download 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'");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.