SDKClient

Devices

SDK reference for devices — Enroll machines into a project, run signed scripts on them, and read the results.

Enroll machines into a project, run signed scripts on them, and read the results.

listDevices

List the devices enrolled into a project, optionally only those with given tags or operating system

GET

Usage:

const result = await swirls.client.devices.listDevices({
  projectId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
tagsstring[]No
os"windows" | "linux" | "macos"No

setDeviceTags

Replace a device's tags. Selectors match devices by their tags.

POST

Usage:

const result = await swirls.client.devices.setDeviceTags({
  projectId: '...',
  deviceId: '...',
  tags: [],
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
deviceIdstringYes
tagsstring[]Yes

Output:

FieldTypeDescription
idstring
projectIdstring
namestring
status"active" | "revoked"
onlineboolean
osstring
archstring
osVersionstring | null
daemonVersionstring
tagsstring[]
lastSeenAtunknown | null
revokedAtunknown | null
createdAtunknown

revokeDevice

Revoke a device. Its credential stops working and its queued runs are canceled.

POST

Usage:

const result = await swirls.client.devices.revokeDevice({
  projectId: '...',
  deviceId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
deviceIdstringYes

Output:

FieldTypeDescription
idstring
projectIdstring
namestring
status"active" | "revoked"
onlineboolean
osstring
archstring
osVersionstring | null
daemonVersionstring
tagsstring[]
lastSeenAtunknown | null
revokedAtunknown | null
createdAtunknown

createEnrollmentToken

Create a token that lets machines enroll into a project. The token is returned once.

POST

Usage:

const result = await swirls.client.devices.createEnrollmentToken({
  projectId: '...',
  name: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
namestringYes
expiresInSecondsnumberNo
maxUsesnumberNo
tagsstring[]No

Output:

FieldTypeDescription
idstring
projectIdstring
namestring
expiresAtunknown
maxUsesnumber
useCountnumber
tagsstring[]
revokedAtunknown | null
createdAtunknown
tokenstring

listEnrollmentTokens

List the enrollment tokens of a project

GET

Usage:

const result = await swirls.client.devices.listEnrollmentTokens({
  projectId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes

revokeEnrollmentToken

Revoke an enrollment token. Devices that already enrolled with it stay enrolled.

POST

Usage:

const result = await swirls.client.devices.revokeEnrollmentToken({
  projectId: '...',
  tokenId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
tokenIdstringYes

Output:

FieldTypeDescription
idstring
projectIdstring
namestring
expiresAtunknown
maxUsesnumber
useCountnumber
tagsstring[]
revokedAtunknown | null
createdAtunknown

createRun

Sign a script for one device and queue it. The device collects it on its next poll.

POST

Usage:

const result = await swirls.client.devices.createRun({
  projectId: '...',
  operationName: '...',
  interpreter: '...',
  script: '...',
  deviceId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
operationNamestringYes
interpreter"powershell" | "sh"Yes
runAs"system" | "signed_in_user"No
scriptstringYes
inputstring | number | boolean | null | JSON value[] | objectNo
timeoutSecondsnumberNo
expiresInSecondsnumberNo
deviceIdstringYes

Output:

FieldTypeDescription
idstring
projectIdstring
deviceIdstring
batchIdstring | null
operationNamestring
interpreter"powershell" | "sh"
runAs"system" | "signed_in_user"
scriptSha256string
timeoutSecondsnumber
status"queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost"
createdAtunknown
expiresAtunknown
deliveredAtunknown | null
completedAtunknown | null
exitCodenumber | null
durationMsnumber | null
refusalReasonstring | null
refusalDetailstring | null
scriptstring
inputstring | number | boolean | null | JSON value[] | object
stdoutstring | null
stderrstring | null
stdoutTruncatedboolean | null
stderrTruncatedboolean | null

createRuns

Sign a script for every active device a selector matches, one run per device. The match is taken when the request is made.

POST

Usage:

const result = await swirls.client.devices.createRuns({
  projectId: '...',
  operationName: '...',
  interpreter: '...',
  script: '...',
  selector: {},
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
operationNamestringYes
interpreter"powershell" | "sh"Yes
runAs"system" | "signed_in_user"No
scriptstringYes
inputstring | number | boolean | null | JSON value[] | objectNo
timeoutSecondsnumberNo
expiresInSecondsnumberNo
selectorobjectYes

Output:

FieldTypeDescription
batchIdstring
runsobject[]

getRun

Get a device run with its script and output

GET

Usage:

const result = await swirls.client.devices.getRun({
  projectId: '...',
  runId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
runIdstringYes

Output:

FieldTypeDescription
idstring
projectIdstring
deviceIdstring
batchIdstring | null
operationNamestring
interpreter"powershell" | "sh"
runAs"system" | "signed_in_user"
scriptSha256string
timeoutSecondsnumber
status"queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost"
createdAtunknown
expiresAtunknown
deliveredAtunknown | null
completedAtunknown | null
exitCodenumber | null
durationMsnumber | null
refusalReasonstring | null
refusalDetailstring | null
scriptstring
inputstring | number | boolean | null | JSON value[] | object
stdoutstring | null
stderrstring | null
stdoutTruncatedboolean | null
stderrTruncatedboolean | null

listRuns

List recent device runs in a project, newest first

GET

Usage:

const result = await swirls.client.devices.listRuns({
  projectId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
deviceIdstringNo
batchIdstringNo
limitnumberNo

cancelRun

Cancel a run the device has not collected yet. A run already delivered cannot be recalled.

POST

Usage:

const result = await swirls.client.devices.cancelRun({
  projectId: '...',
  runId: '...',
})

Input:

ParameterTypeRequiredDescription
projectIdstringYes
runIdstringYes

Output:

FieldTypeDescription
idstring
projectIdstring
deviceIdstring
batchIdstring | null
operationNamestring
interpreter"powershell" | "sh"
runAs"system" | "signed_in_user"
scriptSha256string
timeoutSecondsnumber
status"queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost"
createdAtunknown
expiresAtunknown
deliveredAtunknown | null
completedAtunknown | null
exitCodenumber | null
durationMsnumber | null
refusalReasonstring | null
refusalDetailstring | null
scriptstring
inputstring | number | boolean | null | JSON value[] | object
stdoutstring | null
stderrstring | null
stdoutTruncatedboolean | null
stderrTruncatedboolean | null

On this page