API Methods: Computers
The methods available here give the ability to retrieve computers and to do basic operations on them, such as tagging.
GetComputers
Get a list of computers associated with the account.
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 customize the search.tag: Search for computers with the specified tag.distribution: Search for computers running a specific Ubuntu release (can be code name likejammyor version number like22.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 textreboot.license-id: Search for computers licensed to the specifiedlicense-id.needs:licenseORlicense-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 specifyannotation:<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.ORmust be in all-caps.NOT: search for computers not matching the next term.NOTmust be in all-caps.
If values following a prefix contain spaces or non-ASCII characters, they must be in quotation marks.
These prefixes can be mixed and matched with keywords. For example, the following query would match computers with ‘appserver’ in their title or hostname, either with the tag “server” or running the “jammy” release of Ubuntu:
appserver tag:server OR distribution:jammy
The GetComputers method also supports the following optional arguments:
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.
For example, the following request searches for all computers with the tag “server”, includes their network devices, and with a limit of 20 machines:
?action=GetComputers&query=tag:server&limit=20&with_network=true
The method returns a JSON serialized list of computers:
[{"access_group": "global",
"comment": u"",
"distribution": u"22.04",
"hostname": u"a_comp.example.com",
"id": 12345,
"last_ping_time": None,
"last_exchange_time": "2023-06-3017:59Z",
"title": u"A Computer",
"reboot_required_flag": False,
"tags": ["server"],
"total_memory": None,
"total_swap": None,
"network_devices": [{"broadcast_address": "192.168.1.255",
"interface": "eth0",
"ip_address": "192.168.1.2",
"mac_address": "00:1e:c9:6c:b8:de",
"netmask": "255.255.255.0"}]}]
The JSON equivalent of this output is:
[
{
"access_group": "global",
"comment": "",
"distribution": "22.04",
"hostname": "a_comp.example.com",
"id": 12345,
"last_ping_time": "None",
"last_exchange_time": "2023-06-3017:59Z",
"title": "A Computer",
"reboot_required_flag": false,
"tags": [
"server"
],
"total_memory": "None",
"total_swap": "None",
"network_devices": [
{
"broadcast_address": "192.168.1.255",
"interface": "eth0",
"ip_address": "192.168.1.2",
"mac_address": "00:1e:c9:6c:b8:de",
"netmask": "255.255.255.0"
}
]
}
]
AddAnnotationToComputers
Add a custom annotation to a selection of computers.
Required arguments:
query: A query string used to select the computers for which to add annotations. (SeequeryunderGetComputers, above, for additional details.)key: Annotation key to add to the selected computers.value: Annotation value associated with the provided key to add to the selected computers. (optional)
For example, the following request will add a custom annotation representing physical to all computers running Ubuntu 22.04 (Jammy):
?action=AddAnnotationToComputers&query=distribution:22.04&key=location
&value=BLDG3:FLR2:CAGE101A
RemoveAnnotationFromComputers
Remove a custom annotation with the specified key from a selection of computers.
Required arguments:
query: A query string used to select the computers to remove annotations from. (SeequeryunderGetComputers, above, for additional details.)key: The annotation key to remove.
For example, the following request removes the annotation key location from all computers tagged with “server”:
?action=RemoveAnnotationFromComputers&query=tag:server&key=location
AddTagsToComputers
Add tags to a selection of computers.
Required arguments:
query: A query string used to select the computers to add tags to. (SeequeryunderGetComputers, above, for additional details.)tags: Tag name to be applied, this can have more than one tag, by numbering the tags withtags.1,tags.2,tags.3etc.
For example, the following request will add the tags “server” and “jammy” to all computers running Ubuntu 22.04 (Jammy):
?action=AddTagsToComputers&query=distribution:22.04&tags.1=server
&tags.2=jammy
RemoveTagsFromComputers
Remove tags from a selection of computers.
Required arguments:
query: A query string used to select the computers to remove tags from. (SeequeryunderGetComputers, above, for additional details.)tags: Tag name to be remove, this can have more than one Tag, by numbering the tags withtags.1,tags.2,tags.3etc.
For example, the following request removes the tags “server” and “jammy” from all computers with tag server:
?action=RemoveTagsFromComputers&query=tag:server&tags.1=server
&tags.2=jammy
ChangeComputersAccessGroup
Change the access group for a selection of computers.
Required arguments:
query: A query string used to select the computers to change access group for. (SeequeryunderGetComputers, above, for additional details.)access_group: The name of the access group to assign selected computers to.
This is an example of a valid request:
action=ChangeComputersAccessGroup&query=tag:new-servers
&access_group=server
The method returns a JSON serialized list of computers in the selection which have successfully changed access group:
[{"access_group": "server",
"id": 12345,
"title": u"A Computer",
"comment": u"",
"total_memory": None,
"total_swap": None,
"reboot_required_flag": False,
"hostname": u"a_comp.example.com",
"last_ping_time": None,
"last_exchange_time": "2011-06-3017:59Z",
"tags": ["server"],
"network_devices": [{"broadcast_address": "192.168.1.255",
"interface": "eth0",
"ip_address": "192.168.1.2",
"mac_address": "00:1e:c9:6c:b8:de",
"netmask": "255.255.255.0"}]}]
The JSON equivalent of this output is:
[
{
"access_group": "server",
"id": 12345,
"title": "A Computer",
"comment": "",
"total_memory": "None",
"total_swap": "None",
"reboot_required_flag": false,
"hostname": "a_comp.example.com",
"last_ping_time": "None",
"last_exchange_time": "2011-06-3017:59Z",
"tags": [
"server"
],
"network_devices": [
{
"broadcast_address": "192.168.1.255",
"interface": "eth0",
"ip_address": "192.168.1.2",
"mac_address": "00:1e:c9:6c:b8:de",
"netmask": "255.255.255.0"
}
]
}
]
The following errors may be raised:
InvalidQueryError: If query format is invalid.
RemoveComputers
Remove a list of computers by ID.
Required argument:
computer_ids: A list of computer IDs to remove.
This is an example of a valid HTTP request:
?action=RemoveComputers&computer_ids.1=30&computer_ids.2=43
The equivalent CLI command is:
landscape-api remove-computers 30,43
GetPendingComputers
Get a list of pending computers associated with the account used for authentication:
?action=GetPendingComputers
The method returns a JSON serialized list of pending computers:
[
{
"id": 12345,
"title": "My Server",
"hostname": "server.london.company.com",
"creation_time": "2011-06-3017:59Z",
"vm_info": "xen",
"client_tags": "['london'], ['server']"
}
]
AcceptPendingComputers
Accept a list of pending computers associated with the account used for authentication.
This method takes the following arguments:
computer_ids: A list of pending computer IDs to accept.access_group: The name of the access group to accept the computers to. If not provided, they will be put into the global access group. (optional)
This is an example of a valid HTTP request:
?action=AcceptPendingComputers?computer_ids.1=1&computer_ids.2=2
The equivalent CLI command is:
landscape-api accept-pending-computers 1,2
The method returns a JSON serialized list of accepted computers:
[{"id": 12345,
"title": u"A Computer",
"comment": u"",
"hostname": u"a_comp.example.com",
"last_exchange_time": "2011-06-3017:59Z"}]
The JSON equivalent of this output is:
[
{
"id": 12345,
"title": "A Computer",
"comment": "",
"hostname": "a_comp.example.com",
"last_exchange_time": "2011-06-3017:59Z"
}
]
To replace existing computers, map the pending IDs to the existing ones. For example, via HTTP request:
?action=AcceptPendingComputers?computer_ids.1=1&computer_ids.2=2
&existing_ids.2=3
The equivalent CLI command is:
landscape-api accept-pending-computers --existing-ids 1=1,2=2
The following errors may be raised:
InsufficientLicenses: Insufficient licenses available to accept new computers.UnknownComputer: The provided computers are not known or have been already accepted or rejected.UnknownComputer: The provided computers are not known or have been already accepted or rejected.UnknownAccessGroup: The access group is not known or the person is not authorized to accept pending computers into the access group.
RejectPendingComputers
Reject a list of pending computers associated with the account used for authentication.
This is an example of a valid HTTP request:
?action=RejectPendingComputers?computer_ids.1=1&computer_ids.2=2
The equivalent CLI command is:
landscape-api reject-pending-computers 1,2
CreateCloudOtps
Create one-time passwords used for registration of cloud instances:
?action=CreateCloudOtps?count=3
The method returns a JSON serialized list of one-time passwords, one for each requested:
["otp1", "otp2", "otp3"]
You can then use those OTPs in the client configuration, using cloud-init for example.
RebootComputers
Reboot a list of computers.
Required argument:
computer_ids: A list of computer IDs to reboot.
Optional argument:
deliver_after: Reboot the computer after the specified time. The time format isYYYY-MM-DDTHH:MM:SSZ.
This is an example of a valid HTTP request:
?action=RebootComputers&computer_ids.1=30&computer_ids.2=43
The equivalent CLI command is:
landscape-api reboot-computers 30,43
The method returns a JSON serialized activity:
{u'computer_id': None,
u'creation_time': u'2012-11-19T18:11:51Z',
u'creator': {u'email': u'[email protected]', u'id': 3,
u'name': u'John Smith'},
u'id': 141,
u'parent_id': None,
u'summary': u'Restart computer',
u'type': u'ActivityGroup'}
The JSON equivalent of this output is:
{
"computer_id": "None",
"creation_time": "2012-11-19T18:11:51Z",
"creator": {
"email": "[email protected]",
"id": 3,
"name": "John Smith"
},
"id": 141,
"parent_id": "None",
"summary": "Restart computer",
"type": "ActivityGroup"
}
ShutdownComputers
Shut down a list of computers.
Required argument:
computer_ids: A list of computer IDs to shut down.
Optional argument:
deliver_after: Shutdown the computer after the specified time. The time format isYYYY-MM-DDTHH:MM:SSZ.
This is an example of a valid HTTP request:
?action=ShutdownComputers&computer_ids.1=30&computer_ids.2=43
The equivalent CLI command is:
landscape-api shutdown-computers 30,43
The method returns a JSON serialized activity:
{u'computer_id': None,
u'creation_time': u'2012-11-19T18:14:19Z',
u'creator': {u'email': u'[email protected]', u'id': 3,
u'name': u'John Smith'},
u'id': 147,
u'parent_id': None,
u'summary': u'Shutdown computer',
u'type': u'ActivityGroup'}
The JSON equivalent of this output is:
{
"computer_id": "None",
"creation_time": "2012-11-19T18:14:19Z",
"creator": {
"email": "[email protected]",
"id": 3,
"name": "John Smith"
},
"id": 147,
"parent_id": "None",
"summary": "Shutdown computer",
"type": "ActivityGroup"
}
RenameComputers
Rename a set of computers.
Required argument:
computer_titles: A mapping of computer IDs to titles to set.
This is an example of a valid request:
?action=RenameComputers&computer_titles.30:newname