 param storage A list of storage constraint identifiers, in the form:

<label>:<size>(<tag>[,<tag>[,...])][,<label>:

...]

 type storage unicode

 param interfaces A labeled constraint map associating constraint labels with interface
properties that should be matched. Returned nodes must have one or more interface
matching the specified constraints. The labeled constraint map must be in the format:
<label>:<key>=<value>[,<key2>=<value2>[,...]]

Each key can be one of the following:

 id: Matches an interface with the specific id

 fabric: Matches an interface attached to the specified fabric.
 fabric_class: Matches an interface attached to a fabric with the specified class.
 ip: Matches an interface with the specified IP address assigned to it.
 mode: Matches an interface with the specified mode. (Currently, the only supported mode is
"unconfigured".)
 name: Matches an interface with the specified name. (For example, "eth0".)
 hostname: Matches an interface attached to the node with the specified hostname.
 subnet: Matches an interface attached to the specified subnet.
 space: Matches an interface attached to the specified space.
 subnet_cidr: Matches an interface attached to the specified subnet CIDR. (For example,
"192.168.0.0/24".)
 type: Matches an interface of the specified type. (Valid types: "physical", "vlan", "bond",
"bridge", or "unknown".)
 vlan: Matches an interface on the specified VLAN.
 vid: Matches an interface on a VLAN with the specified VID.
 tag: Matches an interface tagged with the specified tag.
 type interfaces unicode
 param fabrics Set of fabrics that the machine must be associated with in order to be
acquired.

If multiple fabrics names are specified, the machine can be in any of the specified fabrics. To
request multiple possible fabrics to match, this parameter must be repeated in the request with
each value.

 type fabrics unicode (accepts multiple)

 param not_fabrics Fabrics the machine must NOT be associated with in order to be
acquired.

If multiple fabrics names are specified, the machine must NOT be in ANY of them. To request
exclusion of multiple fabrics, this parameter must be repeated in the request with each value.

 type not_fabrics unicode (accepts multiple)

  param fabric_classes Set of fabric class types whose fabrics the machine must be
associated with in order to be acquired.

If multiple fabrics class types are specified, the machine can be in any matching fabric. To
request multiple possible fabrics class types to match, this parameter must be repeated in the
request with each value.

 type fabric_classes unicode (accepts multiple)

 param not_fabric_classes Fabric class types whose fabrics the machine must NOT be
associated with in order to be acquired.

If multiple fabrics names are specified, the machine must NOT be in ANY of them. To request
exclusion of multiple fabrics, this parameter must be repeated in the request with each value.

 type not_fabric_classes unicode (accepts multiple)

 param agent_name An optional agent name to attach to the acquired machine.
 type agent_name unicode
 param comment Optional comment for the event log.
 type comment unicode
 param bridge_all Optionally create a bridge interface for every configured interface on
the machine. The created bridges will be removed once the machine is released. (Default:
False)
 type bridge_all boolean
 param bridge_stp Optionally turn spanning tree protocol on or off for the bridges
created on every configured interface. (Default: off)
 type bridge_stp boolean
 param bridge_fd Optionally adjust the forward delay to time seconds. (Default: 15)
 type bridge_fd integer
 param dry_run Optional boolean to indicate that the machine should not actually be
acquired (this is for support/troubleshooting, or users who want to see which machine
would match a constraint, without acquiring a machine). Defaults to False.
 type dry_run bool
 param verbose Optional boolean to indicate that the user would like additional verbosity
in the constraints_by_type field (each constraint will be prefixed by verbose_, and contain
the full data structure that indicates which machine(s) matched).
 type verbose bool

Returns 409 if a suitable machine matching the constraints could not be found.

POST /api/2.0/machines/ op=release

Release multiple machines.

This places the machines back into the pool, ready to be reallocated.
  param machines system_ids of the machines which are to be released. (An empty list is
acceptable).
 param comment Optional comment for the event log.
 type comment unicode
 return The system_ids of any machines that have their status changed by this call. Thus,
machines that were already released are excluded from the result.

Returns 400 if any of the machines cannot be found. Returns 403 if the user does not have
permission to release any of the machines. Returns a 409 if any of the machines could not be
released due to their current state.

POST /api/2.0/machines/ 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.

Network

Manage a network.

This endpoint is deprecated. Use the new 'subnet' endpoint instead.

DELETE /api/2.0/networks/{name}/

Delete network definition.

This endpoint is no longer available. Use the 'subnet' endpoint instead.

GET /api/2.0/networks/{name}/

Read network definition.

GET /api/2.0/networks/{name}/ op=list_connected_macs

Returns the list of MAC addresses connected to this network.

Only MAC addresses for nodes visible to the requesting user are returned.

POST /api/2.0/networks/{name}/ op=connect_macs

Connect the given MAC addresses to this network.

This endpoint is no longer available. Use the 'subnet' endpoint instead.

POST /api/2.0/networks/{name}/ op=disconnect_macs

Disconnect the given MAC addresses from this network.

This endpoint is no longer available. Use the 'subnet' endpoint instead.

PUT /api/2.0/networks/{name}/

Update network definition.

This endpoint is no longer available. Use the 'subnet' endpoint instead.

 param name A simple name for the network, to make it easier to refer to. Must consist
only of letters, digits, dashes, and underscores.
 param ip Base IP address for the network, e.g. 10.1.0.0. The host bits will be zeroed.
 param netmask Subnet mask to indicate which parts of an IP address are part of the
network address. For example, 255.255.255.0.
 param vlan_tag Optional VLAN tag: a number between 1 and 0xffe (4094) inclusive, or
zero for an untagged network.
 param description Detailed description of the network for the benefit of users and
administrators.

Networks

Manage the networks.

This endpoint is deprecated. Use the new 'subnets' endpoint instead.

GET /api/2.0/networks/

List networks.

 param node Optionally, nodes which must be attached to any returned networks. If more than
one node is given, the result will be restricted to networks that these nodes have in common.

POST /api/2.0/networks/

Define a network.

This endpoint is no longer available. Use the 'subnets' endpoint instead.

Node

Manage an individual Node.

The Node is identified by its system_id.

DELETE /api/2.0/nodes/{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/nodes/{system_id}/

Read a specific Node.

Returns 404 if the node is not found.

GET /api/2.0/nodes/{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/nodes/{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.

Commissioning results

Read the collection of NodeResult in the MAAS.

GET /api/2.0/installation-results/

List NodeResult visible to the user, optionally filtered.

  param system_id An optional list of system ids. Only the results related to the nodes
with these system ids will be returned.
 type system_id iterable
 param name An optional list of names. Only the results with the specified names will be
returned.
 type name iterable
 param result_type An optional result_type. Only the results with the specified
result_type will be returned.
 type name iterable

Node Script

Manage or view a custom script.

DELETE /api/2.0/scripts/{name}

Delete a script.

GET /api/2.0/scripts/{name}

Return a script's metadata.

 param include_script Include the base64 encoded script content.

 type include_script bool

GET /api/2.0/scripts/{name} op=download

Download a script.

 param revision What revision to download, latest by default. Can use rev as a shortcut.
 type revision integer

POST /api/2.0/scripts/{name} op=add_tag

Add a single tag to a script.

 param tag The tag being added.

 type tag unicode

Returns 404 if the script is not found.

POST /api/2.0/scripts/{name} op=remove_tag

Remove a single tag to a script.

 param tag The tag being removed.

  type tag unicode

Returns 404 if the script is not found.

POST /api/2.0/scripts/{name} op=revert

Revert a script to an earlier version.

 param to What revision in the script's history to revert to. This can either be an ID or a
negative number representing how far back to go.
 type to integer

Returns 404 if the script is not found.

PUT /api/2.0/scripts/{name}

Update a commissioning script.

 param name The name of the script.

 type name unicode
 param title The title of the script.
 type title unicode
 param description A description of what the script does.
 type description unicode
 param tags A comma seperated list of tags for this script.
 type tags unicode
 param type The type defines when the script should be used. Can be testing or
commissioning, defaults to testing.
 type script_type unicode
 param timeout How long the script is allowed to run before failing. 0 gives unlimited
time, defaults to 0.
 type timeout unicode
 param destructive Whether or not the script overwrites data on any drive on the
running system. Destructive scripts can not be run on deployed systems. Defaults to false.
 type destructive boolean
 param script The content of the script to be uploaded in binary form. note: this is not a
normal parameter, but a file upload. Its filename is ignored; MAAS will know it by the
name you pass to the request. Optionally you can ignore the name and script parameter in
favor of uploading a single file as part of the request.
 param comment A comment about what this change does.
 type comment unicode

Node Script Result

Manage node script results.

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

Delete a set of results.

id can either by the script set id, current-commissioning, current-testing, or current-installation.

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

View a specific set of results.

id can either by the script set id, current-commissioning, current-testing, or current-installation.

 param include_output Include base64 encoded output from the script.

 type include_output bool
 param filters A comma seperated list to show only results that ran with a script name,
tag, or id.
 type filters unicode

GET /api/2.0/nodes/{system_id}/results/{id}/ op=download

Download a compressed tar containing all results.

id can either by the script set id, current-commissioning, current-testing, or current-installation.

 param filters A comma seperated list to show only results that ran with a script name
or tag.
 type filters unicode
 param output Can be either combined, stdout, stderr, or all. By default only the
combined output is returned.
 type output unicode
 param filetype Filetype to output, can be txt or tar.xz
 type format unicode

Node Script Result

Manage node script results.

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

Return a list of script results grouped by run.

 param type Only return scripts with the given type. This can be commissioning, testing,
or installion. Defaults to showing all.
 type type unicode
 param include_output Include base64 encoded output from the script.
 type include_output bool
  param filters A comma seperated list to show only results with a script name or tag.
 type filters unicode

Node Scripts

Manage custom scripts.

This functionality is only available to administrators.

GET /api/2.0/scripts/

Return a list of stored scripts.

 param type Only return scripts with the given type. This can be testing or
commissioning. Defaults to showing both.
 type script_type unicode
 param include_script Include the base64 encoded script content.
 type include_script bool
 param filters A comma seperated list to show only results with a script name or tag.
 type filters unicode

POST /api/2.0/scripts/

Create a new script.

 param name The name of the script.

 type name unicode
 param title The title of the script.
 type title unicode
 param description A description of what the script does.
 type description unicode
 param tags A comma seperated list of tags for this script.
 type tags unicode
 param type The script_type defines when the script should be used. Can be testing or
commissioning, defaults to testing.
 type script_type unicode
 param timeout How long the script is allowed to run before failing. 0 gives unlimited
time, defaults to 0.
 type timeout unicode
 param destructive Whether or not the script overwrites data on any drive on the
running system. Destructive scripts can not be run on deployed systems. Defaults to false.
 type destructive boolean
 param script The content of the script to be uploaded in binary form. note: this is not a
normal parameter, but a file upload. Its filename is ignored; MAAS will know it by the
name you pass to the request. Optionally you can ignore the name and script parameter in
favor of uploading a single file as part of the request.
  param comment A comment about what this change does.
 type comment unicode

Nodes

Manage the collection of all the nodes in the MAAS.

GET /api/2.0/nodes/

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/nodes/ 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/nodes/ 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.

Notification

Manage an individual notification.

DELETE /api/2.0/notifications/{id}/

Delete a specific notification.

GET /api/2.0/notifications/{id}/

Read a specific notification.

POST /api/2.0/notifications/{id}/ op=dismiss

Dismiss a specific notification.

Returns HTTP 403 FORBIDDEN if this notification is not relevant (targeted) to the invoking
user.

It is safe to call multiple times for the same notification.

PUT /api/2.0/notifications/{id}/

Update a specific notification.

See NotificationsHandler.create for field information.

Notifications

Manage the collection of all the notifications in MAAS.

GET /api/2.0/notifications/

List notifications relevant to the invoking user.

Notifications that have been dismissed are not returned.

POST /api/2.0/notifications/

Create a notification.

This is available to admins only.

 param message The message for this notification. May contain basic HTML; this will be
sanitised before display.
 param context Optional JSON context. The root object must be an object (i.e. a
mapping). The values herein can be referenced by message with Python's "format" (not
%) codes.
 param category Optional category. Choose from: error, warning, success, or info.
Defaults to info.
 param ident Optional unique identifier for this notification.
 param user Optional user ID this notification is intended for. By default it will not be
targeted to any individual user.
 param users Optional boolean, true to notify all users, defaults to false, i.e. not targeted
to all users.
 param admins Optional boolean, true to notify all admins, defaults to false, i.e. not
targeted to all admins.

Note: if neither user nor users nor admins is set, the notification will not be seen by anyone.

Package Repositories

Manage the collection of all Package Repositories in MAAS.

GET /api/2.0/package-repositories/

List all Package Repositories.

POST /api/2.0/package-repositories/

Create a Package Repository.

 param name The name of the Package Repository.

 type name unicode
 param url The url of the Package Repository.
 type url unicode
 param distributions Which package distributions to include.
 type distributions unicode
 param disabled_pockets The list of pockets to disable.
 param disabled_components The list of components to disable. Only applicable to the
default Ubuntu repositories.
 param components The list of components to enable. Only applicable to custom
repositories.
  param arches The list of supported architectures.
 param key The authentication key to use with the repository.
 type key unicode
 param enabled Whether or not the repository is enabled.
 type enabled boolean

Package Repository

Manage an individual Package Repository.

The Package Repository is identified by its id.

DELETE /api/2.0/package-repositories/{id}/

Delete a Package Repository.

Returns 404 if the Package Repository is not found.

GET /api/2.0/package-repositories/{id}/

Read Package Repository.

Returns 404 if the repository is not found.

PUT /api/2.0/package-repositories/{id}/

Update a Package Repository.

 param name The name of the Package Repository.

 type name unicode
 param url The url of the Package Repository.
 type url unicode
 param distributions Which package distributions to include.
 type distributions unicode
 param disabled_pockets The list of pockets to disable.
 param disabled_components The list of components to disable. Only applicable to the
default Ubuntu repositories.
 param components The list of components to enable. Only applicable to custom
repositories.
 param arches The list of supported architectures.
 param key The authentication key to use with the repository.
 type key unicode
 param enabled Whether or not the repository is enabled.
 type enabled boolean

Returns 404 if the Package Repository is not found.

Partitions

Manage partition on a block device.

DELETE /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}

Delete partition.

Returns 404 if the node, block device, or partition are not found.

GET /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}

Read partition.

Returns 404 if the node, block device, or partition are not found.

POST /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}
op=format

Format a partition.

 param fstype Type of filesystem.

 param uuid The UUID for the filesystem.
 param label The label for the filesystem.

Returns 403 when the user doesn't have the ability to format the partition. Returns 404 if the
node, block device, or partition is not found.

POST /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}
op=mount

Mount the filesystem on partition.

 param mount_point Path on the filesystem to mount.

 param mount_options Options to pass to mount(8).

Returns 403 when the user doesn't have the ability to mount the partition. Returns 404 if the
node, block device, or partition is not found.

POST /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}
op=unformat

Unformat a partition.
POST /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partition/{id}
op=unmount

Unmount the filesystem on partition.

Returns 400 if the partition is not formatted or not currently mounted. Returns 403 when the user
doesn't have the ability to unmount the partition. Returns 404 if the node, block device, or
partition is not found.

Partitions

Manage partitions on a block device.

GET /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partitions/

List all partitions on the block device.

Returns 404 if the node or the block device are not found.

POST /api/2.0/nodes/{system_id}/blockdevices/{device_id}/partitions/

Create a partition on the block device.

 param size The size of the partition.

 param uuid UUID for the partition. Only used if the partition table type for the block
device is GPT.
 param bootable If the partition should be marked bootable.

Returns 404 if the node or the block device are not found.

Pod

Manage an individual pod.

The pod is identified by its id.

DELETE /api/2.0/pods/{id}/

Delete a specific Pod.

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

GET /api/2.0/pods/{id}/
GET /api/2.0/pods/{id}/ op=parameters

Obtain pod parameters.