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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
tags | string[] | 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
deviceId | string | Yes | |
tags | string[] | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
name | string | |
status | "active" | "revoked" | |
online | boolean | |
os | string | |
arch | string | |
osVersion | string | null | |
daemonVersion | string | |
tags | string[] | |
lastSeenAt | unknown | null | |
revokedAt | unknown | null | |
createdAt | unknown |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
deviceId | string | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
name | string | |
status | "active" | "revoked" | |
online | boolean | |
os | string | |
arch | string | |
osVersion | string | null | |
daemonVersion | string | |
tags | string[] | |
lastSeenAt | unknown | null | |
revokedAt | unknown | null | |
createdAt | unknown |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
name | string | Yes | |
expiresInSeconds | number | No | |
maxUses | number | No | |
tags | string[] | No |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
name | string | |
expiresAt | unknown | |
maxUses | number | |
useCount | number | |
tags | string[] | |
revokedAt | unknown | null | |
createdAt | unknown | |
token | string |
listEnrollmentTokens
List the enrollment tokens of a project
GET
Usage:
const result = await swirls.client.devices.listEnrollmentTokens({
projectId: '...',
})Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
tokenId | string | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
name | string | |
expiresAt | unknown | |
maxUses | number | |
useCount | number | |
tags | string[] | |
revokedAt | unknown | null | |
createdAt | unknown |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
operationName | string | Yes | |
interpreter | "powershell" | "sh" | Yes | |
runAs | "system" | "signed_in_user" | No | |
script | string | Yes | |
input | string | number | boolean | null | JSON value[] | object | No | |
timeoutSeconds | number | No | |
expiresInSeconds | number | No | |
deviceId | string | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
deviceId | string | |
batchId | string | null | |
operationName | string | |
interpreter | "powershell" | "sh" | |
runAs | "system" | "signed_in_user" | |
scriptSha256 | string | |
timeoutSeconds | number | |
status | "queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost" | |
createdAt | unknown | |
expiresAt | unknown | |
deliveredAt | unknown | null | |
completedAt | unknown | null | |
exitCode | number | null | |
durationMs | number | null | |
refusalReason | string | null | |
refusalDetail | string | null | |
script | string | |
input | string | number | boolean | null | JSON value[] | object | |
stdout | string | null | |
stderr | string | null | |
stdoutTruncated | boolean | null | |
stderrTruncated | boolean | 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
operationName | string | Yes | |
interpreter | "powershell" | "sh" | Yes | |
runAs | "system" | "signed_in_user" | No | |
script | string | Yes | |
input | string | number | boolean | null | JSON value[] | object | No | |
timeoutSeconds | number | No | |
expiresInSeconds | number | No | |
selector | object | Yes |
Output:
| Field | Type | Description |
|---|---|---|
batchId | string | |
runs | object[] |
getRun
Get a device run with its script and output
GET
Usage:
const result = await swirls.client.devices.getRun({
projectId: '...',
runId: '...',
})Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
runId | string | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
deviceId | string | |
batchId | string | null | |
operationName | string | |
interpreter | "powershell" | "sh" | |
runAs | "system" | "signed_in_user" | |
scriptSha256 | string | |
timeoutSeconds | number | |
status | "queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost" | |
createdAt | unknown | |
expiresAt | unknown | |
deliveredAt | unknown | null | |
completedAt | unknown | null | |
exitCode | number | null | |
durationMs | number | null | |
refusalReason | string | null | |
refusalDetail | string | null | |
script | string | |
input | string | number | boolean | null | JSON value[] | object | |
stdout | string | null | |
stderr | string | null | |
stdoutTruncated | boolean | null | |
stderrTruncated | boolean | null |
listRuns
List recent device runs in a project, newest first
GET
Usage:
const result = await swirls.client.devices.listRuns({
projectId: '...',
})Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
deviceId | string | No | |
batchId | string | No | |
limit | number | No |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | |
runId | string | Yes |
Output:
| Field | Type | Description |
|---|---|---|
id | string | |
projectId | string | |
deviceId | string | |
batchId | string | null | |
operationName | string | |
interpreter | "powershell" | "sh" | |
runAs | "system" | "signed_in_user" | |
scriptSha256 | string | |
timeoutSeconds | number | |
status | "queued" | "delivered" | "succeeded" | "failed" | "timed_out" | "refused" | "canceled" | "expired" | "lost" | |
createdAt | unknown | |
expiresAt | unknown | |
deliveredAt | unknown | null | |
completedAt | unknown | null | |
exitCode | number | null | |
durationMs | number | null | |
refusalReason | string | null | |
refusalDetail | string | null | |
script | string | |
input | string | number | boolean | null | JSON value[] | object | |
stdout | string | null | |
stderr | string | null | |
stdoutTruncated | boolean | null | |
stderrTruncated | boolean | null |