This method is reserved for admin users and returns a 403 if the user is not one.

This returns the pod parameters, if any, configured for a pod. For some types of pod this will
include private information such as passwords and secret keys.

Returns 404 if the pod is not found.

POST /api/2.0/pods/{id}/ op=compose

Compose a machine from Pod.

All fields below are optional:

 param cores Minimum number of CPU cores.

 param memory Minimum amount of memory (MiB).
 param cpu_speed Minimum amount of CPU speed (MHz).
 param architecture Architecture for the machine. Must be an architecture that the pod
supports.
 param storage A list of storage constraint identifiers, in the form:
<label>:<size>(<tag>[,<tag>[,...])][,<label>:

...]

 type storage unicode

 param hostname Hostname for the newly composed machine.
 type hostname unicode
 param domain ID of domain to place the newly composed machine in.
 param zone ID of zone place the newly composed machine in.

Returns 404 if the pod is not found. Returns 403 if the user does not have permission to compose
machine.

POST /api/2.0/pods/{id}/ op=refresh

Refresh a specific Pod.

Performs pod discovery and updates all discovered information and discovered machines.

Returns 404 if the pod is not found. Returns 403 if the user does not have permission to refresh
the pod.

PUT /api/2.0/pods/{id}/

Update a specific Pod.

 param name Name for the pod (optional).

Note: 'type' cannot be updated on a Pod. The Pod must be deleted and re-added to change the
type.

Returns 404 if the pod is not found. Returns 403 if the user does not have permission to update
the pod.

Pods

Manage the collection of all the pod in the MAAS.

GET /api/2.0/pods/

List pods.

Get a listing of all the pods.

POST /api/2.0/pods/

Create a Pod.

 param type Type of pod to create (rsd, virsh).

 param name Name for the pod (optional).

Returns 503 if the pod could not be discovered. Returns 404 if the pod is not found. Returns 403
if the user does not have permission to create a pod.

RackController

Manage an individual rack controller.

The rack controller is identified by its system_id.

DELETE /api/2.0/rackcontrollers/{system_id}/

Delete a specific Node.

Returns 404 if the node is not found. Returns 403 if the user does not have permission to delete
the node. Returns 204 if the node is successfully deleted.

GET /api/2.0/rackcontrollers/{system_id}/

Read a specific Node.

Returns 404 if the node is not found.

GET /api/2.0/rackcontrollers/{system_id}/ op=details

Obtain various system details.

For example, LLDP and lshw XML dumps.

Returns a {detail_type: xml, ...} map, where detail_type is something like "lldp" or
"lshw".

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because
JSON can't do binary content without applying additional encoding like base-64.

Returns 404 if the node is not found.

GET /api/2.0/rackcontrollers/{system_id}/ op=list_boot_images

List all available boot images.

Shows all available boot images and lists whether they are in sync with the region.

Returns 404 if the rack controller is not found.

GET /api/2.0/rackcontrollers/{system_id}/ op=power_parameters

Obtain power parameters.

This method is reserved for admin users and returns a 403 if the user is not one.

This returns the power parameters, if any, configured for a node. For some types of power control
this will include private information such as passwords and secret keys.

Returns 404 if the node is not found.

GET /api/2.0/rackcontrollers/{system_id}/ op=query_power_state

Query the power state of a node.

Send a request to the node's power controller which asks it about the node's state. The reply to
this could be delayed by up to 30 seconds while waiting for the power controller to respond. Use
this method sparingly as it ties up an appserver thread while waiting.

 param system_id The node to query.

 return a dict whose key is "state" with a value of one of 'on' or 'off'.

Returns 404 if the node is not found. Returns node's power state.
POST /api/2.0/rackcontrollers/{system_id}/ op=abort

Abort a node's current operation.

 param comment Optional comment for the event log.

 type comment unicode

Returns 404 if the node could not be found. Returns 403 if the user does not have permission to
abort the current operation.

POST /api/2.0/rackcontrollers/{system_id}/ op=import_boot_images

Import the boot images on this rack controller.

Returns 404 if the rack controller is not found.

POST /api/2.0/rackcontrollers/{system_id}/ op=power_off

Power off a node.

 param stop_mode An optional power off mode. If 'soft', perform a soft power down if the
node's power type supports it, otherwise perform a hard power off. For all values other
than 'soft', and by default, perform a hard power off. A soft power off generally asks the
OS to shutdown the system gracefully before powering off, while a hard power off occurs
immediately without any warning to the OS.
 type stop_mode unicode
 param comment Optional comment for the event log.
 type comment unicode

Returns 404 if the node is not found. Returns 403 if the user does not have permission to stop the
node.

POST /api/2.0/rackcontrollers/{system_id}/ op=power_on

Turn on a node.

 param user_data If present, this blob of user-data to be made available to the nodes
through the metadata service.
 type user_data base64-encoded unicode
 param comment Optional comment for the event log.
 type comment unicode

Ideally we'd have MIME multipart and content-transfer-encoding etc. deal with the encapsulation
of binary data, but couldn't make it work with the framework in reasonable time so went for a
dumb, manual encoding instead.
Returns 404 if the node is not found. Returns 403 if the user does not have permission to start the
machine. Returns 503 if the start-up attempted to allocate an IP address, and there were no IP
addresses available on the relevant cluster interface.

POST /api/2.0/rackcontrollers/{system_id}/ op=test

Begin testing process for a node.

 param enable_ssh Whether to enable SSH for the testing environment using the user's
SSH key(s).
 type enable_ssh bool ('0' for False, '1' for True)
 param testing_scripts A comma seperated list of testing script names and tags to be
run. By default all tests tagged 'commissioning' will be run.
 type testing_scripts string

A node in the 'ready', 'allocated', 'deployed', 'broken', or any failed state may run tests. If testing is
started and successfully passes from a 'broken', or any failed state besides 'failed commissioning'
the node will be returned to a ready state. Otherwise the node will return to the state it was when
testing started.

Returns 404 if the node is not found.

PUT /api/2.0/rackcontrollers/{system_id}/

Update a specific Rack controller.

 param power_type The new power type for this rack controller. If you use the default
value, power_parameters will be set to the empty string. Available to admin users. See the
Power types section for a list of the available power types.
 type power_type unicode
 param power_parameters_{param1} The new value for the 'param1' power parameter.
Note that this is dynamic as the available parameters depend on the selected value of the
rack controller's power_type. Available to admin users. See the Power types section for a
list of the available power parameters for each power type.
 type power_parameters_{param1} unicode
 param power_parameters_skip_check Whether or not the new power parameters for
this rack controller should be checked against the expected power parameters for the rack
controller's power type ('true' or 'false'). The default is 'false'.
 type power_parameters_skip_check unicode
 param zone Name of a valid physical zone in which to place this rack controller.
 type zone unicode

Returns 404 if the rack controller is not found. Returns 403 if the user does not have permission
to update the rack controller.
RackControllers

Manage the collection of all rack controllers in MAAS.

GET /api/2.0/rackcontrollers/

List Nodes visible to the user, optionally filtered by criteria.

Nodes are sorted by id (i.e. most recent last) and grouped by type.

 param hostname An optional hostname. Only nodes relating to the node with the
matching hostname will be returned. This can be specified multiple times to see multiple
nodes.
 type hostname unicode
 param mac_address An optional MAC address. Only nodes relating to the node owning
the specified MAC address will be returned. This can be specified multiple times to see
multiple nodes.
 type mac_address unicode
 param id An optional list of system ids. Only nodes relating to the nodes with matching
system ids will be returned.
 type id unicode
 param domain An optional name for a dns domain. Only nodes relating to the nodes in
the domain will be returned.
 type domain unicode
 param zone An optional name for a physical zone. Only nodes relating to the nodes in
the zone will be returned.
 type zone unicode
 param agent_name An optional agent name. Only nodes relating to the nodes with
matching agent names will be returned.
 type agent_name unicode

GET /api/2.0/rackcontrollers/ op=describe_power_types

Query all of the rack controllers for power information.

 return a list of dicts that describe the power types in this format.

GET /api/2.0/rackcontrollers/ op=is_registered

Returns whether or not the given MAC address is registered within this MAAS (and attached to a
non-retired node).

 param mac_address The mac address to be checked.

 type mac_address unicode
 return 'true' or 'false'.
 rtype unicode
Returns 400 if any mandatory parameters are missing.

GET /api/2.0/rackcontrollers/ op=power_parameters

Retrieve power parameters for multiple machines.

 param id An optional list of system ids. Only machines with matching system ids will be
returned.
 type id iterable
 return A dictionary of power parameters, keyed by machine system_id.

Raises 403 if the user is not an admin.

POST /api/2.0/rackcontrollers/ op=import_boot_images

Import the boot images on all rack controllers.

POST /api/2.0/rackcontrollers/ op=set_zone

Assign multiple nodes to a physical zone at once.

 param zone Zone name. If omitted, the zone is "none" and the nodes will be taken out of
their physical zones.
 param nodes system_ids of the nodes whose zones are to be set. (An empty list is
acceptable).

Raises 403 if the user is not an admin.

RAID Device

Manage a specific RAID device on a machine.

DELETE /api/2.0/nodes/{system_id}/raid/{id}/

Delete RAID on a machine.

Returns 404 if the machine or RAID is not found. Returns 409 if the machine is not Ready.

GET /api/2.0/nodes/{system_id}/raid/{id}/

Read RAID device on a machine.

Returns 404 if the machine or RAID is not found.

PUT /api/2.0/nodes/{system_id}/raid/{id}/

Update RAID on a machine.

  param name Name of the RAID.
 param uuid UUID of the RAID.
 param add_block_devices Block devices to add to the RAID.
 param remove_block_devices Block devices to remove from the RAID.
 param add_spare_devices Spare block devices to add to the RAID.
 param remove_spare_devices Spare block devices to remove from the RAID.
 param add_partitions Partitions to add to the RAID.
 param remove_partitions Partitions to remove from the RAID.
 param add_spare_partitions Spare partitions to add to the RAID.
 param remove_spare_partitions Spare partitions to remove from the RAID.

Returns 404 if the machine or RAID is not found. Returns 409 if the machine is not Ready.

RAID Devices

Manage all RAID devices on a machine.

GET /api/2.0/nodes/{system_id}/raids/

List all RAID devices belonging to a machine.

Returns 404 if the machine is not found.

POST /api/2.0/nodes/{system_id}/raids/

Creates a RAID

 param name Name of the RAID.

 param uuid UUID of the RAID.
 param level RAID level.
 param block_devices Block devices to add to the RAID.
 param spare_devices Spare block devices to add to the RAID.
 param partitions Partitions to add to the RAID.
 param spare_partitions Spare partitions to add to the RAID.

Returns 404 if the machine is not found. Returns 409 if the machine is not Ready.

RegionController

Manage an individual region controller.

The region controller is identified by its system_id.

DELETE /api/2.0/regioncontrollers/{system_id}/

Delete a specific Node.

Returns 404 if the node is not found. Returns 403 if the user does not have permission to delete
the node. Returns 204 if the node is successfully deleted.

GET /api/2.0/regioncontrollers/{system_id}/

Read a specific Node.

Returns 404 if the node is not found.

GET /api/2.0/regioncontrollers/{system_id}/ op=details

Obtain various system details.

For example, LLDP and lshw XML dumps.

Returns a {detail_type: xml, ...} map, where detail_type is something like "lldp" or
"lshw".

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because
JSON can't do binary content without applying additional encoding like base-64.

Returns 404 if the node is not found.

GET /api/2.0/regioncontrollers/{system_id}/ op=power_parameters

Obtain power parameters.

This method is reserved for admin users and returns a 403 if the user is not one.

This returns the power parameters, if any, configured for a node. For some types of power control
this will include private information such as passwords and secret keys.

Returns 404 if the node is not found.

PUT /api/2.0/regioncontrollers/{system_id}/

Update a specific Region controller.

 param power_type The new power type for this region controller. If you use the default
value, power_parameters will be set to the empty string. Available to admin users. See the
Power types section for a list of the available power types.
 type power_type unicode
 param power_parameters_{param1} The new value for the 'param1' power parameter.
Note that this is dynamic as the available parameters depend on the selected value of the
region controller's power_type. Available to admin users. See the Power types section for
a list of the available power parameters for each power type.
 type power_parameters_{param1} unicode
  param power_parameters_skip_check Whether or not the new power parameters for
this region controller should be checked against the expected power parameters for the
region controller's power type ('true' or 'false'). The default is 'false'.
 type power_parameters_skip_check unicode
 param zone Name of a valid physical zone in which to place this region controller.
 type zone unicode

Returns 404 if the region controller is not found. Returns 403 if the user does not have permission
to update the region controller.

RegionControllers

Manage the collection of all region controllers in MAAS.

GET /api/2.0/regioncontrollers/

List Nodes visible to the user, optionally filtered by criteria.

Nodes are sorted by id (i.e. most recent last) and grouped by type.

 param hostname An optional hostname. Only nodes relating to the node with the
matching hostname will be returned. This can be specified multiple times to see multiple
nodes.
 type hostname unicode
 param mac_address An optional MAC address. Only nodes relating to the node owning
the specified MAC address will be returned. This can be specified multiple times to see
multiple nodes.
 type mac_address unicode
 param id An optional list of system ids. Only nodes relating to the nodes with matching
system ids will be returned.
 type id unicode
 param domain An optional name for a dns domain. Only nodes relating to the nodes in
the domain will be returned.
 type domain unicode
 param zone An optional name for a physical zone. Only nodes relating to the nodes in
the zone will be returned.
 type zone unicode
 param agent_name An optional agent name. Only nodes relating to the nodes with
matching agent names will be returned.
 type agent_name unicode

GET /api/2.0/regioncontrollers/ op=is_registered

Returns whether or not the given MAC address is registered within this MAAS (and attached to a
non-retired node).
  param mac_address The mac address to be checked.
 type mac_address unicode
 return 'true' or 'false'.
 rtype unicode

Returns 400 if any mandatory parameters are missing.

POST /api/2.0/regioncontrollers/ op=set_zone

Assign multiple nodes to a physical zone at once.

 param zone Zone name. If omitted, the zone is "none" and the nodes will be taken out of
their physical zones.
 param nodes system_ids of the nodes whose zones are to be set. (An empty list is
acceptable).

Raises 403 if the user is not an admin.

SSH Key

Manage an SSH key.

SSH keys can be retrieved or deleted.

DELETE /api/2.0/account/prefs/sshkeys/{id}/

DELETE an SSH key.

Returns 404 if the key does not exist. Returns 401 if the key does not belong to the calling user.

GET /api/2.0/account/prefs/sshkeys/{id}/

GET an SSH key.

Returns 404 if the key does not exist.

SSH Keys

Manage the collection of all the SSH keys in this MAAS.

GET /api/2.0/account/prefs/sshkeys/

List all keys belonging to the requesting user.

POST /api/2.0/account/prefs/sshkeys/

Add a new SSH key to the requesting user's account.

The request payload should contain the public SSH key data in form data whose name is "key".

POST /api/2.0/account/prefs/sshkeys/ op=import

Import the requesting user's SSH keys.

Import SSH keys for a given protocol and authorization ID in protocol:auth_id format.

SSL Key

Manage an SSL key.

SSL keys can be retrieved or deleted.

DELETE /api/2.0/account/prefs/sslkeys/{id}/

DELETE an SSL key.

Returns 401 if the key does not belong to the requesting user. Returns 204 if the key is
successfully deleted.

GET /api/2.0/account/prefs/sslkeys/{id}/

GET an SSL key.

Returns 404 if the key with id is not found. Returns 401 if the key does not belong to the
requesting user.

SSL Keys

Operations on multiple keys.

GET /api/2.0/account/prefs/sslkeys/

List all keys belonging to the requesting user.

POST /api/2.0/account/prefs/sslkeys/

Add a new SSL key to the requesting user's account.

The request payload should contain the SSL key data in form data whose name is "key".
Space

Manage space.

DELETE /api/2.0/spaces/{id}/

Delete space.

Returns 404 if the space is not found.

GET /api/2.0/spaces/{id}/

Read space.

Returns 404 if the space is not found.

PUT /api/2.0/spaces/{id}/

Update space.

 param name Name of the space.

 param description Description of the space.

Returns 404 if the space is not found.

Spaces

Manage spaces.

GET /api/2.0/spaces/

List all spaces.

POST /api/2.0/spaces/

Create a space.

 param name Name of the space.

 param description Description of the space.

Static route

Manage static route.

DELETE /api/2.0/static-routes/{id}/

Delete static route.

Returns 404 if the static route is not found.

GET /api/2.0/static-routes/{id}/

Read static route.

Returns 404 if the static route is not found.

PUT /api/2.0/static-routes/{id}/

Update static route.

 param source Source subnet for the route.

 param destination Destination subnet for the route.
 param gateway_ip IP address of the gateway on the source subnet.
 param metric Weight of the route on a deployed machine.

Returns 404 if the static route is not found.

Static routes

Manage static routes.

GET /api/2.0/static-routes/

List all static routes.

POST /api/2.0/static-routes/

Create a static route.

 param source Source subnet for the route.

 param destination Destination subnet for the route.
 param gateway_ip IP address of the gateway on the source subnet.
 param metric Weight of the route on a deployed machine.

Subnet

Manage subnet.
DELETE /api/2.0/subnets/{id}/

Delete subnet.

Returns 404 if the subnet is not found.

GET /api/2.0/subnets/{id}/

Read subnet.

Returns 404 if the subnet is not found.

GET /api/2.0/subnets/{id}/ op=ip_addresses

Returns a summary of IP addresses assigned to this subnet.

Optional parameters

with_username If False, suppresses the display of usernames associated with each address.
(Default: True)

with_summary If False, suppresses the display of nodes, BMCs, and and DNS records associated
with each address. (Default: True)

with_node_summary Deprecated form of with_summary.

GET /api/2.0/subnets/{id}/ op=reserved_ip_ranges

Lists IP ranges currently reserved in the subnet.

Returns 404 if the subnet is not found.

GET /api/2.0/subnets/{id}/ op=statistics

Returns statistics for the specified subnet, including:

num_available: the number of available IP addresses largest_available: the largest number of

contiguous free IP addresses num_unavailable: the number of unavailable IP addresses
total_addresses: the sum of the available plus unavailable addresses usage: the (floating point)
usage percentage of this subnet usage_string: the (formatted unicode) usage percentage of this
subnet ranges: the specific IP ranges present in ths subnet (if specified)
Optional parameters

include_ranges If True, includes detailed information about the usage of this range.

include_suggestions If True, includes the suggested gateway and dynamic range for this subnet, if
it were to be configured.