Manage computers with the REST API#

The REST API computer endpoints find, modify, and add team computers and control which users and Access Groups can connect to them. Use these endpoints to automate tasks otherwise performed in the Teams dashboard, for example to create installers from a provisioning script or remove retired computers.

Applies to#

• A Jump Desktop for Teams team, and an API token from a team Admin. Admin (Read-Only) users and read-only tokens are restricted to GET requests. See Get started with the REST API for tokens, team IDs, and error responses.
• Samples use placeholder IDs T-EXAMPLE123 (team), D-EXAMPLE456 (computer), U-EXAMPLE111 (user), and G-EXAMPLE789 (Access Group), and read the token from JUMP_API_TOKEN.
• Python samples use the requests package. JavaScript samples require Node.js 18 or later and use top-level await, so save them as .mjs files.

To perform these tasks in the Teams dashboard, see Add and manage computers.

Find a computer by name#

GET /v1/team/{teamID}/devices returns every computer on the team in the devices array. To filter by name, add the name parameter:

Matching is case-insensitive. If no computer matches, devices is an empty array.

curl --fail-with-body -sS -G https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/devices \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  --data-urlencode "name=*web*"

import os

import requests

resp = requests.get(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/devices",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    params={"name": "*web*"},
)
if not resp.ok:
    raise SystemExit(f"{resp.status_code} {resp.text}")

for device in resp.json()["devices"]:
    print(device["id"], device["name"])

const url = new URL("https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/devices");
url.searchParams.set("name", "*web*");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.JUMP_API_TOKEN}` },
});
if (!res.ok) {
  console.error(res.status, await res.text());
  process.exit(1);
}

const { devices } = await res.json();
for (const device of devices) console.log(device.id, device.name);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$uri = "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/devices?name=*web*"

try {
    (Invoke-RestMethod -Uri $uri -Headers $headers).devices | Select-Object id, name
} catch {
    Write-Error "$($_.Exception.Response.StatusCode.value__) $($_.ErrorDetails.Message)"
    exit 1
}

Each computer includes the following fields. Fields without a value are omitted.

Get, rename, or remove a computer#

Getting or renaming a computer that is not on the team returns 404.

Rename a computer#

Renaming changes the computer's name for everyone on the team. The response contains id and the new name.

curl --fail-with-body -sS -X PATCH \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456 \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reception PC"}'

import os

import requests

resp = requests.patch(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    json={"name": "Reception PC"},
)
resp.raise_for_status()
print(resp.json())

const res = await fetch(
  "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.JUMP_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Reception PC" }),
  },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$body = @{ name = "Reception PC" } | ConvertTo-Json

Invoke-RestMethod -Method Patch -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456" `
    -Headers $headers -ContentType "application/json" -Body $body

Remove a computer#

curl --fail-with-body -sS -X DELETE \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456 \
  -H "Authorization: Bearer $JUMP_API_TOKEN"

Add computers with a pre-configured installer#

POST /v1/team/{teamID}/invite/device creates a pre-configured Jump Desktop Connect installer. A computer running the installer joins the team without a sign-in.

The 201 response includes:

Download a file from connectDownloads and run it on the computer. Do not rename the downloaded file before running it. To install on many computers, see Deploy Connect to many computers. To look up user and group IDs, see Manage users and access with the REST API.

curl --fail-with-body -sS -X POST \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/invite/device \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Front office", "groups": ["G-EXAMPLE789"], "expirySecs": 86400}'

import os

import requests

resp = requests.post(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/invite/device",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    json={"name": "Front office", "groups": ["G-EXAMPLE789"], "expirySecs": 86400},
)
resp.raise_for_status()
installer = resp.json()
print(installer["id"], installer["connectDownloads"]["winmsi"])

const res = await fetch("https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/invite/device", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JUMP_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Front office", groups: ["G-EXAMPLE789"], expirySecs: 86400 }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const installer = await res.json();
console.log(installer.id, installer.connectDownloads.winmsi);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$body = @{ name = "Front office"; groups = @("G-EXAMPLE789"); expirySecs = 86400 } | ConvertTo-Json

$installer = Invoke-RestMethod -Method Post -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/invite/device" `
    -Headers $headers -ContentType "application/json" -Body $body
$installer.connectDownloads.winmsi

If the team has reached its installer limit, the request fails with 400 and code invite-limit-reached. To create more installers, delete installers you no longer need.

Delete an installer#

Call DELETE /v1/team/{teamID}/invite/device/{inviteID} with the installer's id as inviteID. After deletion, copies of the installer and its Connect Code stop working; computers the installer already added remain on the team. An unknown ID returns 404 with code invite-not-found.

curl --fail-with-body -sS -X DELETE \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/invite/device/AC-EXAMPLE321 \
  -H "Authorization: Bearer $JUMP_API_TOKEN"

Set who can connect to a computer#

Each request accepts users (user IDs) and groups (Access Group IDs). To look up IDs, see Manage users and access with the REST API. For how access works, see Control access with Access Groups.

Adding a group with a Connect Configuration clears any configuration assigned directly to the computer. See Configure computers with Connect Configurations.

Replace access#

curl --fail-with-body -sS -X PUT \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/members \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"users": ["U-EXAMPLE111"], "groups": ["G-EXAMPLE789"]}'

import os

import requests

resp = requests.put(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/members",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    json={"users": ["U-EXAMPLE111"], "groups": ["G-EXAMPLE789"]},
)
resp.raise_for_status()

const res = await fetch(
  "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/members",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.JUMP_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ users: ["U-EXAMPLE111"], groups: ["G-EXAMPLE789"] }),
  },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$body = @{ users = @("U-EXAMPLE111"); groups = @("G-EXAMPLE789") } | ConvertTo-Json

Invoke-RestMethod -Method Put -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/members" `
    -Headers $headers -ContentType "application/json" -Body $body

Add access to several computers#

The bulk requests return 200 even when the change fails for some computers. Check the errors field in the response, which lists each failed computer and is omitted when no computer failed.

curl --fail-with-body -sS -X PATCH \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/members \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"devices": ["D-EXAMPLE456", "D-EXAMPLE457"], "users": ["U-EXAMPLE111"]}'

import os

import requests

resp = requests.patch(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/members",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    json={"devices": ["D-EXAMPLE456", "D-EXAMPLE457"], "users": ["U-EXAMPLE111"]},
)
resp.raise_for_status()
for error in resp.json().get("errors", []):
    print("Failed:", error)

const res = await fetch("https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/members", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.JUMP_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ devices: ["D-EXAMPLE456", "D-EXAMPLE457"], users: ["U-EXAMPLE111"] }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { errors = [] } = await res.json();
for (const error of errors) console.error("Failed:", error);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$body = @{ devices = @("D-EXAMPLE456", "D-EXAMPLE457"); users = @("U-EXAMPLE111") } | ConvertTo-Json

$result = Invoke-RestMethod -Method Patch -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/members" `
    -Headers $headers -ContentType "application/json" -Body $body
$result.errors

Get launch URLs for a computer#

GET /v1/team/{teamID}/device/{deviceID}/urls returns links for use in your own tools. The links include the computer's current name, so request them again after renaming the computer.

connect and askScreenShare work only on devices with the Jump Desktop app installed. Both are jump:// links; see Launch links and connection files.

curl --fail-with-body -sS \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/urls \
  -H "Authorization: Bearer $JUMP_API_TOKEN"

import os

import requests

resp = requests.get(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/urls",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
)
resp.raise_for_status()
print(resp.json()["connect"])

const res = await fetch(
  "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/urls",
  { headers: { Authorization: `Bearer ${process.env.JUMP_API_TOKEN}` } },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).connect);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }

(Invoke-RestMethod -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/urls" -Headers $headers).connect

Tags and annotations#

Annotations are key-value pairs stored on a computer. Keys are 1 to 64 characters; values are up to 2,048 characters.

Adding or updating changes only the keys you send; other annotations remain unchanged.

In the Teams dashboard, a computer's tags are stored as one annotation with the key tag and a comma-separated value, and most other keys appear as custom fields. Writing tag replaces all of the computer's tags.

curl --fail-with-body -sS -X POST \
  https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/annotations \
  -H "Authorization: Bearer $JUMP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"annotations": [{"key": "tag", "value": "Finance,London"}, {"key": "Asset number", "value": "A-1042"}]}'

import os

import requests

resp = requests.post(
    "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/annotations",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
    json={
        "annotations": [
            {"key": "tag", "value": "Finance,London"},
            {"key": "Asset number", "value": "A-1042"},
        ]
    },
)
resp.raise_for_status()

const res = await fetch(
  "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/annotations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JUMP_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      annotations: [
        { key: "tag", value: "Finance,London" },
        { key: "Asset number", value: "A-1042" },
      ],
    }),
  },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }
$body = @{
    annotations = @(
        @{ key = "tag"; value = "Finance,London" },
        @{ key = "Asset number"; value = "A-1042" }
    )
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Method Post -Uri "https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/device/D-EXAMPLE456/annotations" `
    -Headers $headers -ContentType "application/json" -Body $body

Related#

• REST API reference
• Get started with the REST API
• Manage users and access with the REST API
• Add and manage computers in the Teams dashboard