---
title: "QuantumSync API over websockets"
method: GET
path: "/api/quantumsync"
tags: ["Quantum Sync"]
---

# QuantumSync API over websockets

`GET /api/quantumsync`

## Request

- Base URL: `https://passivelogic.com` (the document declares no server; this is the origin it was published from)
- URL: `https://passivelogic.com/api/quantumsync`
- Auth: one of:
  - API key in header `X-PL-AUTH`
  - API key in header `Authorization: PL-API-KEY`
  - API key in header `PL-API-KEY`
  - HTTP basic
- TypeScript: <https://skmtc.dev/passivelogic/apis/passivelogic-http-api/docs/api/quantumsync/get.ts> (a function with typed inputs; its response is checked against the schema)

# Custom QuantumSync/ShadowClient API:

## Error and retry convention
Clients own retry policy from stable error-code categories. Request and domain errors (441x and 443x–445x)
require a corrected request rather than a blind replay. Backend errors (446x) may be retried with bounded
exponential backoff; internal errors (447x) should be surfaced rather than automatically replayed. A sync
response with an unconfirmed `transactionOutcome` must be reconciled before replaying the request.

## QuantumSync QuantumSyncRequestTypes:
### `start`: authenticates and specifies an initial context. note: the id for start and updateContext is used to key a Dictionary[String:AnyRootedQuantumGraph]
ex)
```json
{
    "type": "start",
    "id": "site",
    "appType":"BuildingStudio"
    "payload": {
        "authToken": "REDACTED",
        "ID": "ACAF9E07-5031-4BC2-A8C5-D2C6598D83DE",
        "from": "Site",
        "include": [
            "Site",
            "Building",
            "Floor",
            "Zone"
    ]
    }
}
```

### `updateContext`: change the current context / graph in memory.
note: the previous graph/context can be returned from memory by using updateContext id: <previous id used in start or updateContext>.
Up to 5 contexts can be loaded before prevention (error) or deleteContext message needed to free up loaded count to load a new context.

ex)
```json
{
    "type": "updateContext",
    "id": "building",
    "payload": {
        "ID": "ACAF9E07-5031-4BC2-A8C5-D2C6598D83DE",
        "from": "Building",
        "include": [
            "Site",
            "Floor",
            "Zone",
            "Image",
            "Surface",
            "Adjacency",
            "System",
            "Quanta",
            "Manufacturer",
            "Equipment",
            "Property",
            "Location"
        ]
    }
}
```

### `deleteContext`: delete/clear the context out of memory.
ex)
```json
{
    "type": "deleteContext",
    "id": "building",
    "payload": {}
}
```

### `sync`: create/update/delete QuantumObjects via a FlatGraphDiff as the payload.

Executing concurrent sync's is not allowed. If there is a sync already processing and another sync is requested before the response of the first sync is sent, then the 2nd symc will return an error saying there is a sync currently processing, and to wait until its finished before requesting another sync.

ex)
```json
{
    "type": "sync",
    "id": "F5B6BC51-B991-440C-8ACB-B55C65FD7C24",
    "payload": {
        "added": [],
        "updated": [
            {
                "description": null,
                "ID": "80187B0B-CEEB-488A-A9B7-06784CFB0464",
                "longitude": null,
                "locationPropertyID": null,
                "elevation": null,
                "latitude": null,
                "address": null,
                "timeZone": null,
                "siteIDs": [
                    "7E7E04B4-8F32-4585-839D-E0EFC7BB3544"
                ],
                "weatherSourceIDs": [],
                "locked": false,
                "authGroupID": "A1EBEC59-D887-473F-A5C5-7CBD4ADB2556",
                "__typename": "Location",
                "name": "foo"
            }
        ],
        "removed": []
    }
}
```

### `syncEphemeral`: create/update/delete QuantumObjects via a FlatGraphDiff as the payload, do not write them to the database,
and discard them at the end of the websocket session.
ex)
```json
{
    "type": "syncEphemeral",
    "id": "F5B6BC51-B991-440C-8ACB-B55C65FD7C24",
    "payload": {
        "added": [],
        "updated": [
            {
                "description": null,
                "ID": "80187B0B-CEEB-488A-A9B7-06784CFB0464",
                "longitude": null,
                "locationPropertyID": null,
                "elevation": null,
                "latitude": null,
                "address": null,
                "timeZone": null,
                "siteIDs": [
                    "7E7E04B4-8F32-4585-839D-E0EFC7BB3544"
                ],
                "weatherSourceIDs": [],
                "locked": false,
                "authGroupID": "A1EBEC59-D887-473F-A5C5-7CBD4ADB2556",
                "__typename": "Location",
                "name": "foo"
            }
        ],
        "removed": []
    }
}
```

### `propertyHistory`: Get history data for a property & listen for updates.
ex)
```json
{
    "type": "propertyHistory",
    "id": "propertyHistory1",
    "payload": {
        "propertyIDs": ["E585C3B8-F1E5-40D0-83A7-658B248DF103"],
        "startAt": "2024-01-01T00:00:00Z",
        "endAt": "2024-01-01T01:00:00Z",
        "resample": {
            "interval": {
                "to": "minutely",
                "reduceUsing": "avg",
                "fillUsing": "interpolate"
        },
        "pollIntervalSec": 60
    }
}

### `propertyHistoryStop`: Stop listening for property history updates
ex)
```json
{
    "type": "propertyHistoryStop",
    "id": "propertyHistory1"
}
```

### `writeHistory`: Write historical data to a property
ex)
```json
{
    "type": "writeHistory",
    "id": "writeHistory",
    "payload": {
        "histories": [
            {
                "propertyID": "E585C3B8-F1E5-40D0-83A7-658B248DF103",
                "time": "2024-01-01T00:00:00Z",
                "value": 5.0
            }
        ]
    }
}
```

---

[API](https://skmtc.dev/passivelogic/apis/passivelogic-http-api.md) - [All operations](https://skmtc.dev/passivelogic/apis/passivelogic-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/passivelogic/apis/passivelogic-http-api/revisions/28fce63bcdbb?raw)