API Endpoints: Computers

yanisa-hs · March 22, 2024, 2:48am

Note: These endpoints are only available to beta users at this time.

GET `/computers`

Get information on a list of computers associated with the account.

Path parameters:

None

Query parameters:

query: A query string with space-separated tokens used to filter the returned computers. Words provided as search parameters are treated as keywords, matching the hostname or the computer title. Selector prefixes can be used to further customise the search.
tag: Search for computers with the specified tag.
distribution: Search for computers running a specific Ubuntu release (can be code name like jammy or version number like 22.04).
hostname: Search for computers with the exact hostname.
title: Search for computers with the exact title.
alert: Search for computers with a named alert being active. Alerts can be one of the following: package-upgrades, security-upgrades, package-profiles, package-reporter, computer-offline, computer-reboot.
access-group: Search for computers that belong to the access group with the specified name.
id: Select the specified numeric computer ID.
mac: Search for computers with the specified MAC address, which can be a substring of the full address.
ip: Search for computers with the specified IP address, which can be a substring of the full address. No network classing is done.
search: Select computers based on the result of the named search.
needs:reboot: Search for computers that have the reboot required flag set. Note that with this particular criteria, the only possible value for it is the text reboot.
license-id: Search for computers licensed to the specified license-id.
needs:license OR license-id:none: Search for computers that do not have a Landscape license, and, as a result, are not managed.
annotation: Search for computers which define the specified annotation key. Optionally specify annotation:<key>:<string> which will only return computers whose key matches and value also contains the <string> specified.
OR: Search for computers matching term A or term B. OR must be in all-caps.
NOT: search for computers not matching the next term. NOT must be in all-caps.
limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.
with_network: If true, include the details of all network devices attached to the computer.
with_hardware: If true, include the details of all hardware information known.
with_annotations: If true, include the details of all custom annotation information known.

Example request:

curl -X GET https://landscape.canonical.com/api/v2/computers?limit=1 -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 13,
  "results": [
        {
          "id": 1,
          "title": "Application Server 1",
          "comment": "",
          "hostname": "appserv1",
          "total_memory": 1024,
          "total_swap": 1024,
          "reboot_required_flag": false,
          "update_manager_prompt": "normal",
          "clone_id": null,
          "secrets_name": null,
          "last_exchange_time": null,
          "last_ping_time": "2024-02-07T21:21:41Z",
          "tags": [
            "lucid",
            "server",
            "webfarm"
          ],
          "access_group": "server",
          "distribution": "10.04",
          "cloud_instance_metadata": {},
          "vm_info": null,
          "container_info": null,
          "ubuntu_pro_info": null,
          "is_wsl_instance": false,
          "children": [],
          "parent": null
        }
  ],
  "next": "https://landscape.canonical.com/api/v2/computers?limit=1&offset=1",
  "previous": null
}

GET `/computers/<int:computer_id>`

Get information on a specific computer in the account.

Path parameters:

computer_id: An ID assigned to a specific computer.

Query parameters:

query: A query string with space-separated tokens used to filter the returned computers. Words provided as search parameters are treated as keywords, matching the hostname or the computer title. Selector prefixes can be used to further customise the search.
tag: Search for computers with the specified tag.
distribution: Search for computers running a specific Ubuntu release (can be code name like jammy or version number like 22.04).
hostname: Search for computers with the exact hostname.
title: Search for computers with the exact title.
alert: Search for computers with a named alert being active. Alerts can be one of the following: package-upgrades, security-upgrades, package-profiles, package-reporter, computer-offline, computer-reboot.
access-group: Search for computers that belong to the access group with the specified name.
id: Select the specified numeric computer ID.
mac: Search for computers with the specified MAC address, which can be a substring of the full address.
ip: Search for computers with the specified IP address, which can be a substring of the full address. No network classing is done.
search: Select computers based on the result of the named search.
needs:reboot: Search for computers that have the reboot required flag set. Note that with this particular criteria, the only possible value for it is the text reboot.
license-id: Search for computers licensed to the specified license-id.
needs:license OR license-id:none: Search for computers that do not have a Landscape license, and, as a result, are not managed.
annotation: Search for computers which define the specified annotation key. Optionally specify annotation:<key>:<string> which will only return computers whose key matches and value also contains the <string> specified.
OR: Search for computers matching term A or term B. OR must be in all-caps.
NOT: search for computers not matching the next term. NOT must be in all-caps.
limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.
with_network: If true, include the details of all network devices attached to the computer.
with_hardware: If true, include the details of all hardware information known.
with_annotations: If true, include the details of all custom annotation information known.

Example request:

curl -X GET https://landscape.canonical.com/api/v2/computers/1 -H "Authorization: Bearer $JWT"

Example output:

{
  "id": 1,
  "title": "Application Server 1",
  "comment": "",
  "hostname": "appserv1",
  "total_memory": 1024,
  "total_swap": 1024,
  "reboot_required_flag": false,
  "update_manager_prompt": "normal",
  "clone_id": null,
  "secrets_name": null,
  "last_exchange_time": null,
  "last_ping_time": "2024-02-07T21:21:41Z",
  "tags": [
        "lucid",
        "server",
        "webfarm"
  ],
  "access_group": "server",
  "distribution": "10.04",
  "cloud_instance_metadata": {},
  "vm_info": null,
  "container_info": null,
  "ubuntu_pro_info": null,
  "is_wsl_instance": false,
  "children": [],
  "parent": null
}

GET `/computers/activities`

Get details of the activities for specified computer(s).

Path parameters:

None

Query parameters:

(Required) computer_ids: An ID assigned to a specific computer.
limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.

Example request:

curl -X GET "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1" -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 26,
  "results": [
        {
          "id": 143,
          "creation_time": "2024-03-01T20:58:14Z",
          "creator": {
            "name": "John Smith",
            "email": "john@example.com",
            "id": 1
          },
          "type": "ChangePackagesRequest",
          "summary": "Remove package abs-guide",
          "result_text": null,
          "computer_id": 1,
          "approval_time": null,
          "delivery_time": null,
          "deliver_after_time": null,
          "deliver_before_time": null,
          "package_ids": [
            73
          ],
          "changes": [
            {
              "package": "abs-guide",
              "complemented": false,
              "type": "remove",
              "version": "10-3"
            }
          ],
          "parent_id": 142,
          "modification_time": "2024-03-01T20:58:14Z",
          "completion_time": null,
          "schedule_before_time": null,
          "schedule_after_time": null,
          "result_code": null,
          "activity_status": "undelivered",
          "children": []
        }
  ],
  "next": "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1&offset=1",
  "previous": null
}

GET `/computers/wsl-hosts`

Gets a list of Windows computers that are hosting at least one WSL instance.

Path parameters:

None

Query parameters:

query: A query string with space-separated tokens used to filter the returned computers. Words provided as search parameters are treated as keywords, matching the hostname or the computer title. Selector prefixes can be used to further customise the search.

Example request:

curl -X GET https://landscape.canonical.com/api/v2/computers/wsl-hosts -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 1,
  "results": [
        {
          "id": 6,
          "title": "Jane's Windows Laptop",
          "comment": "",
          "hostname": "jane",
          "total_memory": 1024,
          "total_swap": 1024,
          "reboot_required_flag": false,
          "update_manager_prompt": "normal",
          "clone_id": null,
          "secrets_name": null,
          "last_exchange_time": null,
          "last_ping_time": "2024-02-07T21:16:41Z",
          "tags": [
            "laptop",
            "windows"
          ],
          "access_group": "server",
          "distribution": "10 / 11",
          "cloud_instance_metadata": {},
          "vm_info": null,
          "container_info": null,
          "ubuntu_pro_info": null,
          "is_wsl_instance": false,
          "children": [
            {
              "id": 11,
              "title": "Bionic WSL",
              "comment": "",
              "hostname": "bionic-wsl",
              "total_memory": 1024,
              "total_swap": 1024,
              "reboot_required_flag": false,
              "update_manager_prompt": "normal",
              "clone_id": null,
              "secrets_name": null,
              "last_exchange_time": null,
              "last_ping_time": "2024-02-07T21:11:41Z",
              "tags": [
                "bionic",
                "wsl"
              ],
              "access_group": "global",
              "distribution": "18.04",
              "cloud_instance_metadata": {},
              "vm_info": null,
              "container_info": null,
              "ubuntu_pro_info": null,
              "is_wsl_instance": true
            },
            {
              "id": 12,
              "title": "Focal WSL",
              "comment": "",
              "hostname": "focal-wsl",
              "total_memory": 1024,
              "total_swap": 1024,
              "reboot_required_flag": false,
              "update_manager_prompt": "normal",
              "clone_id": null,
              "secrets_name": null,
              "last_exchange_time": null,
              "last_ping_time": "2024-02-07T21:10:41Z",
              "tags": [
                "focal",
                "wsl"
              ],
              "access_group": "global",
              "distribution": "20.04",
              "cloud_instance_metadata": {},
              "vm_info": null,
              "container_info": null,
              "ubuntu_pro_info": null,
              "is_wsl_instance": true
            }
          ],
          "parent": null
        }
  ],
  "next": null,
  "previous": null
}

GET `/computers/<int:computer_id>/groups`

Get all user groups for the provided computer ID.

Path parameters:

computer_id: An ID assigned to a specific computer.

Query parameters:

None

GET `/computers/<int:computer_id>/packages`

Get packages associated with a computer ID.

Path parameters:

computer_id: An ID assigned to a specific computer.

Query parameters:

query: A query string used to select computers to query packages on.
search: A string to restrict the search to (optional). All fields are searched, not just those returned. (e.g., description)
names: Restrict the search to these package names. Multiple names can be specified by numbering the names with names.1, names.2, etc.
installed: If true only packages in the installed state will be returned, if false only packages not installed will be returned. If not given both installed and not installed packages will be returned.
available: If true only packages in the available state will be returned, if false only packages not available will be returned. If not given both available and not available packages will be returned.
upgrade: If true, only installable packages that are upgrades for an installed one are returned. If false, only installable packages that are not upgrades are returned. If not given, packages will be returned regardless of whether they are upgrades or not.
held: If true, only installed packages that are held on computers are returned. If false, only packages that are not held on computers are returned. If not given, packages will be returned regardless of the held state.
limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.

Example request:

curl -X GET "https://landscape.canonical.com/api/v2/computers/23/packages?limit=2" -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 92372,
  "results": [
    {
      "name": "0ad",
      "summary": "Real-time strategy game",
      "status": "available",
      "current_version": null,
      "available_version": "0.0.25b-2"
    },
    {
      "name": "0ad-data",
      "summary": "Real-time strategy game (data files)",
      "status": "available",
      "current_version": null,
      "available_version": "0.0.25b-1"
    }
  ],
  "next": "https://landscape.canonical.com/api/v2/computers/23/packages?limit=2&offset=2",
  "previous": null
}

GET `/computers/<int:computer_id>/snaps/installed`

List all installed snaps on a single computer.

Path parameters:

computer_id: An ID assigned to a specific computer.

Query parameters:

limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.

Example request:

curl -X GET "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2" -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 4,
  "results": [
        {
          "version": "4.0.9-a29c6f1",
          "revision": "24061",
          "tracking_channel": "4.0/stable/ubuntu-20.04",
          "held_until": null,
          "confinement": "strict",
          "snap": {
            "id": "J60k4GY0HppDwOeW8dZdWc8obX0xujRu",
            "name": "lxd",
            "publisher": {
              "username": "canonical",
              "validation": "verified"
            },
            "summary": "LXD - container and VM manager"
          }
        },
        {
          "version": "2.61.1",
          "revision": "20671",
          "tracking_channel": "latest/stable",
          "held_until": null,
          "confinement": "strict",
          "snap": {
            "id": "PM2rV4ml8uWu4RDBT8dSGnJUYbevVhc4",
            "name": "snapd",
            "publisher": {
              "username": "canonical",
              "validation": "verified"
            },
            "summary": "Daemon and tooling that enable snap packages"
          }
        }
  ],
  "next": "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2&offset=2",
  "previous": null
}

GET `/computers/<int:computer_id>/users/<string:username>/groups`

Get all the groups for the provided username on the given computer ID.

Path parameters:

computer_id: An ID assigned to a specific computer.
username: The username of the account.

Query parameters:

None

Example request:

curl -X GET "https://landscape.canonical.com/api/v2/computers/22/users/ubuntu/groups" -H "Authorization: Bearer $JWT"

Example output:

{
  "groups": [
        {
          "id": 1020,
          "computer_id": 22,
          "gid": 4,
          "name": "adm"
        },
        {
          "id": 1022,
          "computer_id": 22,
          "gid": 29,
          "name": "audio"
        },
  ]
}

GET `/computers/<int:computer_id>/processes`

Gets the active processes for the computer.

Path parameters:

computer_id: An ID assigned to a specific computer.

Query parameters:

limit: The maximum number of results returned by the method. It defaults to 1000.
offset: The offset inside the list of results.

Example request:

curl -X GET "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2" -H "Authorization: Bearer $JWT"

Example output:

{
  "count": 84,
  "results": [
        {
          "id": 2551,
          "computer_id": 22,
          "pid": 1525,
          "gid": 1000,
          "name": "(sd-pam)",
          "state": "S",
          "start_time": "2024-02-07T20:26:55Z",
          "vm_size": 104024,
          "cpu_utilisation": 0
        },
        {
          "id": 2552,
          "computer_id": 22,
          "pid": 1530,
          "gid": 1000,
          "name": "-bash",
          "state": "S",
          "start_time": "2024-02-07T20:26:55Z",
          "vm_size": 10032,
          "cpu_utilisation": 0
        }
  ],
  "next": "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2&offset=2",
  "previous": null
}

POST `/computers/<int:computer_id>/usergroups/update_bulk`

Update all the groups for the provided username on the given computer ID.

Required path parameters:

computer_id: An ID assigned to a specific computer.

Required parameters:

usernames: A list of strings of the usernames to be updated.
action: The action to be performed on the users.
groupnames: A list of strings with the group names.

Optional parameters:

None

Example request:

curl -X POST "http://landscape.canonical.com/api/v2/computers/1/usergroups/update_bulk" -H "Authorization: Bearer $JWT"  -d '{"action": "add", "usernames": ["john", "jane"], "groupnames": ["finance", "admin"]}'

Example output:

{
  "id": 407,
  "creation_time": "2024-03-21T21:52:12Z",
  "creator": {
    "name": "John Smith",
    "email": "john@example.com",
    "id": 1
  },
  "type": "ActivityGroup",
  "summary": "Adding user(s) to group(s)",
  "completion_time": null,
  "parent_id": null,
  "deliver_delay_window": 0,
  "result_text": null,
  "result_code": null,
  "activity_status": "undelivered"
}

API Endpoints: Computers

GET /computers

GET /computers/<int:computer_id>

GET /computers/activities

GET /computers/wsl-hosts

GET /computers/<int:computer_id>/groups

GET /computers/<int:computer_id>/packages

GET /computers/<int:computer_id>/snaps/installed

GET /computers/<int:computer_id>/users/<string:username>/groups

GET /computers/<int:computer_id>/processes

POST /computers/<int:computer_id>/usergroups/update_bulk

GET `/computers`

GET `/computers/<int:computer_id>`

GET `/computers/activities`

GET `/computers/wsl-hosts`

GET `/computers/<int:computer_id>/groups`

GET `/computers/<int:computer_id>/packages`

GET `/computers/<int:computer_id>/snaps/installed`

GET `/computers/<int:computer_id>/users/<string:username>/groups`

GET `/computers/<int:computer_id>/processes`

POST `/computers/<int:computer_id>/usergroups/update_bulk`