Manage computers with the REST API¶

Find, change, and add team computers, and control who can connect to them. Use it to automate what you'd otherwise do 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 can only make 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 need Node.js 18 or later and use top-level await: save them as .mjs files.

To do the same 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 devices. Add name to filter:

Matching ignores case. With no match, 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 these fields. Fields with no value are omitted.

Get, rename, or remove a computer¶

Getting or renaming a computer that isn't on the team returns 404.

Rename a computer¶

This changes the computer's name for everyone on the team. The response returns 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 that runs it joins the team with no sign-in.

The 201 response includes:

Download a file from connectDownloads and run it on the computer. Don't 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: delete installers you no longer need.

Delete an installer¶

Call DELETE /v1/team/{teamID}/invite/device/{inviteID} with the installer's id as inviteID. Copies of the installer and its Connect Code stop working. Computers it already added stay 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 takes users (user IDs) and groups (Access Group IDs). See Manage users and access with the REST API to look up IDs, and Control access with Access Groups for how access works.

Adding a group that has 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 some computers fail. Check errors in the response: it lists each computer that failed and is omitted when none did.

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 you can put in your own tools. They include the computer's current name, so get them again after renaming a computer.

connect and askScreenShare only work where the Jump Desktop app is installed. They're 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 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 stay.

In the dashboard, a computer's tags are one annotation with the key tag and a comma-separated value, and most other keys show 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