Docs

Appearance

Open console

Reference

Syncs

REST API reference for Syncs: manage syncs and their locks. 13 operations.

Reference7 min read

For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/syncs ​

  • Request: GET /v1/users/{user}/syncs
  • Operation: ListSyncs
  • Operation ID: Sync_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "created": 1792263090740,
    "enabled": true,
    "modified": 1792263090740,
    "name": "Firmware uploads",
    "sync": "firmware_uploads"
  },
  {
    "created": 1792263090740,
    "description": "Only one controller can dose at a time",
    "enabled": true,
    "modified": 1792263090740,
    "name": "Dosing pump",
    "sync": "dosing_pump"
  }
]

POST /v1/users/{user}/syncs ​

  • Request: POST /v1/users/{user}/syncs
  • Operation: CreateSync
  • Operation ID: Sync_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

A sync is a shared semaphore: 'available' slots that devices or scripts take with locks (POST .../syncs/{sync}/locks) and release, e.g. to let only N devices use a resource at the same time. 'timeout' (seconds) is the default lock lifetime; 0 = until released.

FieldTypeRequiredConstraintsDescription
configobjectyes
configobjectnoVariant 1:
config.availableintegeryesMinimum: 0Variant 1:
config.timeoutintegernoMinimum: 0Variant 1:
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanyes
namestringyesMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
syncstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Limit concurrent uploads

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "available": 5,
    "timeout": 600
  },
  "enabled": true,
  "name": "Firmware uploads",
  "sync": "firmware_uploads"
}'

Example body: One device at a time

json
{
  "config": {
    "available": 1,
    "timeout": 120
  },
  "description": "Only one controller can dose at a time",
  "enabled": true,
  "name": "Dosing pump",
  "sync": "dosing_pump"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/syncs/{sync} ​

  • Request: GET /v1/users/{user}/syncs/
  • Operation: ReadSyncConfig
  • Operation ID: Sync_ReadConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Limit concurrent uploads)

json
{
  "config": {
    "available": 5,
    "timeout": 600
  },
  "created": 1792263090740,
  "enabled": true,
  "modified": 1792263090740,
  "name": "Firmware uploads",
  "sync": "firmware_uploads"
}

Response example (200, One device at a time)

json
{
  "config": {
    "available": 1,
    "timeout": 120
  },
  "created": 1792263090740,
  "description": "Only one controller can dose at a time",
  "enabled": true,
  "modified": 1792263090740,
  "name": "Dosing pump",
  "sync": "dosing_pump"
}

PUT /v1/users/{user}/syncs/{sync} ​

  • Request: PUT /v1/users/{user}/syncs/
  • Operation: UpdateSync
  • Operation ID: Sync_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
configobjectno
configobjectnoVariant 1:
config.availableintegeryesMinimum: 0Variant 1:
config.timeoutintegernoMinimum: 0Variant 1:
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Disable

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

Example body: More slots

json
{
  "config": {
    "available": 10,
    "timeout": 600
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/syncs/{sync} ​

  • Request: DELETE /v1/users/{user}/syncs/
  • Operation: DeleteSync
  • Operation ID: Sync_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/syncs/{sync}/clone ​

  • Request: GET /v1/users/{user}/syncs/{sync}/clone
  • Operation: CloneSyncConfig
  • Operation ID: Sync_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/syncs/{sync}/clone ​

  • Request: POST /v1/users/{user}/syncs/{sync}/clone
  • Operation: CloneSync
  • Operation ID: Sync_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
syncstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "sync": "copy_of_sync"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "sync": "line_2_sync"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/syncs/{sync}/locks ​

  • Request: GET /v1/users/{user}/syncs/{sync}/locks
  • Operation: ListSyncLocks
  • Operation ID: Sync_ListLocks
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/locks' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "created": 1792263090741,
    "lock": "pump_controller_1",
    "modified": 1792263090741,
    "name": "Controller 1"
  },
  {
    "created": 1792263090741,
    "lock": "bulk_job",
    "modified": 1792263090741,
    "slots": 2
  }
]

POST /v1/users/{user}/syncs/{sync}/locks ​

  • Request: POST /v1/users/{user}/syncs/{sync}/locks
  • Operation: CreateSyncLock
  • Operation ID: Sync_CreateLock
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Request body (application/json, required)

Takes 'slots' (default 1) of the sync. Fails when not enough slots are free. 'timeout' (seconds) overrides the sync default; without lock id a random one is assigned. Delete the lock to release it.

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
lockstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
slotsnumberno
timeoutnumberno

Example request: Take one slot

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/locks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "lock": "pump_controller_1",
  "name": "Controller 1"
}'

Example body: Two slots for 60 seconds

json
{
  "lock": "bulk_job",
  "slots": 2,
  "timeout": 60
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/syncs/{sync}/locks/{lock} ​

  • Request: GET /v1/users/{user}/syncs/{sync}/locks/
  • Operation: ReadSyncLockConfig
  • Operation ID: Sync_ReadLockConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes
lockpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/locks/YOUR_LOCK' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Take one slot)

json
{
  "created": 1792263090741,
  "lock": "pump_controller_1",
  "modified": 1792263090741,
  "name": "Controller 1"
}

Response example (200, Two slots for 60 seconds)

json
{
  "created": 1792263090741,
  "lock": "bulk_job",
  "modified": 1792263090741,
  "slots": 2,
  "timeout": 60
}

PUT /v1/users/{user}/syncs/{sync}/locks/{lock} ​

  • Request: PUT /v1/users/{user}/syncs/{sync}/locks/
  • Operation: UpdateSyncLock
  • Operation ID: Sync_UpdateLock
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes
lockpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Rename

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/locks/YOUR_LOCK' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Controller 1 - night shift"
}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/syncs/{sync}/locks/{lock} ​

  • Request: DELETE /v1/users/{user}/syncs/{sync}/locks/
  • Operation: DeleteSyncLock
  • Operation ID: Sync_DeleteLock
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes
lockpathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/locks/YOUR_LOCK' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/syncs/{sync}/projects ​

  • Request: PUT /v1/users/{user}/syncs/{sync}/projects
  • Operation: UpdateSyncProjects
  • Operation ID: Sync_UpdateProjects
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
syncpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
(body)array of stringnoProjects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/syncs/YOUR_SYNC/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json
[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json
[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

StatusDescription
200ok
401unauthorized
403forbidden