NAV
cURL Python

Cloudify REST API V3.1

Basic usage

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/<endpoint>"
# Using ClodifyClient
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3.1/<endpoint>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers)
response.json()

Welcome to Cloudify’s REST API Documentation!

The base URI for the v3.1 REST API is: /api/v3.1.

Starting from Cloudify 4.0.0, all communication to the server requires:

Every Cloudify Manager has a default tenant, called default_tenant. The default_tenant tenant is created during bootstrap.

In addition to the default_tenant, every Cloudify Manager includes a bootstrap Admin. The bootstrap Admin is the Admin user that created during the bootstrap.

In addition to the user credentials, every request must also specify a tenant in the header.

In the case of using the Cloudify community edition or if you have not created any new tenant, you can use the default_tenant as the tenant for the request.

Parameters

Response Fields Filtering (Projection)

Request Example (receive only the id and created_at fields)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-api>/api/v3.1/blueprints?_include=id,created_at"
# Using ClodifyClient
blueprints = client.blueprints.list(_include=['id','created_at'])
for blueprint in blueprints:
  print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
querystring = {'_include': 'id,created_at'}
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:12:36.626Z",
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

You can choose to have only specific fields in the response by using the _include query parameter.

The parameter value is a comma separated list of fields to include in the response, e.g. _include=field1,field2,field3

Note that specified field names must be part of the resource schema, otherwise an error is raised.

Query Filtering (Selection)

Request Example (requesting only blueprints which id is _myblueprint1 or _myblueprint2)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/blueprints?_include=id,created_at&id=my-blueprint-1&id=my-blueprint-2"
# Using ClodifyClient
blueprints = client.blueprints.list(
    _include=['id','created_at'],
    id=['my-blueprint-1', 'my-blueprint-2'],
)
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v3.1/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,created_at',
    'id': ['my-blueprint-1', 'my-blueprint-2'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:34:52.911Z",
      "id": "my-blueprint-1"
    },
    {
      "created_at": "2017-04-17T12:34:57.256Z",
      "id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 2
    }
  }
}

You can make your query more specific by using filters.

Filters are query parameters where the key is a field name and the value is a field value, e.g. id=my-specific-id

Filters also accept multiple values (OR) by using multiple parameters of the same key, e.g. id=my-specific-id&id=another-id

Sorting

Request Example #1 (sort deployments by id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3.1/deployments?_include=id,blueprint_id&_sort=-id"
# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort='-id',
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': '-id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Request Example #2 (sort deployments by blueprint_id ascending and id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3.1/deployments?_include=id,blueprint_id&_sort=blueprint_id&_sort=-id"
# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort=['blueprint_id', '-id'],
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': ['blueprint_id', '-id'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #2

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Sort resources by using the _sort query parameter, e.g. _sort=id

The default sort order is ascending; to make it descending, prefix the field with a minus sign, e.g. _sort=-id (example #1)

Sorting also works on multiple fields by using multiple _sort parameters, where the sort sequence corresponds to the order of _sort parameters in the request (example #2).

Pagination

Request Example (skip 1 resource, get size of 4)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/events?_size=4&_offset=1&_include=timestamp"
# Using CloudifyClient
events = client.events.list(
    _size=4,
    _offset=1,
    _include=['timestamp'],
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/events'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_size': '4',
    '_offset': '1',
    '_include':'timestamp',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "timestamp": "2017-04-17T13:53:22.570Z"
    },
    {
      "timestamp": "2017-04-17T13:53:10.558Z"
    },
    {
      "timestamp": "2017-04-17T13:53:09.799Z"
    },
    {
      "timestamp": "2017-04-17T13:52:54.549Z"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 20,
      "offset": 1,
      "size": 4
    }
  }
}

If the response includes too many items for the client to handle at once, use pagination to get only a subset of the results, defined by two parameters:

* both parameters are optional.

* in any case, with or without pagination, max size of the result will be less than max_results parameters, which is 1000 by default. max_results parameters is part of the manager_rest config.

The response metadata returns the requested parameters, and a total field which indicates the size of the full set.

Authentication

Authentication headers should be added to every request sent to a secured manager.
Any header can be used, as long as it’s support by one of the manager’s authentication providers. The default manager configuration supports basic HTTP authentication (examples #1, #2) and tokens (example #3).
Valid credentials do not affect the returned response, but invalid credentials return a “User Unauthorized” error.

Request Example #1 (Get the server’s status, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/status?_include=status"
# Using CloudifyClient
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'status'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "status": "running"
}

Request Example #2 (Get a token, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "<manager-ip>/api/v3.1/tokens"
# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3.1/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example #2

{
  "role": "admin",
  "value": "WyIwIiwiMzE0OTNmNWFjOTE1MzdhM2IyZWM4NTFhYWY4NzU0NWEiXQ.C9Z82w.dlVgLkkyeWZgZP06xMxe8Omht90"
}

Request Example #3 (Get all the blueprints, authenticate with a token)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    --header "Authentication-Token: <manager-token>" \
    "http://<manager-ip>/api/v3.1/blueprints?_include=id"
# Using CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    tenant='<manager-tenant>',
    token='<manager-token>',
)
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
headers = {
    'Tenant': '<manager-tenant>',
    'Autentication-Token': '<manage-token>',
}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    headers=headers,
    params=querystring,
)
response.json()

Response Example #3

{
  "items": [
    {
      "id": "my-blueprint-1"
    },
    {
      "id": "my-blueprint-2"
    },
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

Agents

Supported for Cloudify Manager 4.5 and above.

The Agents Resource

This resource represents a Cloudify Agent, and is used for examining the details of installed agents.

Attributes:

Attribute Type Description
id string Unique identifier of the node instance that installed the agent
host_id string Unique identifier of the node instance that the agent is installed on. Identical to id except for deployment proxy agents.
ip string IP of the host the agent is installed on
install_methods string The agent’s install_method (remote/plugin/init_script/provided)
system string Description of the OS the agent is installed on (the linux distribution name, or “windows”)
version string Cloudify version of the agent software
node string ID of the node that installed the agent
deployment string ID of the deployment that installed the agent

List agents

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/agents?node_ids=<node_1>&node_ids=<node_2>"
# Using CloudifyClient
client.agents.list(node_ids=['node_1', 'node_2'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/agents'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'node_ids': ['node_1', 'node_2']
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
    "items": [
        {
            "node": "x",
            "ip": "127.0.0.1",
            "system": "centos core",
            "install_method": "remote",
            "version": "4.5.0",
            "deployment": "d4",
            "host_id": "x_asa5b3",
            "id": "x_asa5b3"
        }
    ],
    "metadata": {
        "pagination": {
            "total": 1,
            "offset": 0,
            "size": 1
        }
    }
}

Gets the list of installed agents.

URI Parameters

For additional filtering of the agents list, the following parameters can be provided:

Response

A list of Agent resources.

Blueprints

The Blueprint Resource

Attributes:

Attribute Type Description
created_at datetime The time the blueprint was uploaded to the manager.
description string The blueprint’s description.
id string A unique identifier for the blueprint.
main_file_name string The blueprint’s main file name.
plan dict The parsed result of the blueprint.
updated_at datetime The last time the blueprint was updated.

Get Blueprint

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints?id=<blueprint-id>&_include=id"
# Using CloudifyClient
client.blueprints.get(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<blueprint-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

GET "{manager-ip}/api/v3.1/blueprints?id={blueprint-id}"

Gets a specific blueprint.

URI Parameters

Response

A Blueprint resource.

Upload Blueprint

Request Example

# create blueprint from blueprint_archive_url
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>?application_file_name=<blueprint-id>.yaml&visibility=<visibility>&blueprint_archive_url=https://url/to/archive/master.zip"

# create blueprint from uploaded archive
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>?application_file_name=<blueprint-id>.yaml&visibility=<visibility>" -T <blueprint_archive>.tar.gz
# Using CloudifyClient
client.blueprints._upload(
    blueprint_id='<blueprint-id>',
    archive_location='https://url/to/archive/master.zip',
    application_file_name='<blueprint-id>.yaml',
    visibility='<visibility>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'application_file_name': '<blueprint-id>.yaml',
    'blueprint_archive_url': 'https://url/to/archive/master.zip',
    'visibility': '<visibility>'
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Cloudify's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T10:56:06.267Z",
  "updated_at": "2017-04-19T10:56:06.267Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "tenant",
  "plan": {
    ...
  },
  "id": "hello-world"
}

PUT "{manager-ip}/api/v3.1/blueprints/{blueprint-id}?application_file_name={blueprint-id}.yaml&blueprint_archive_url=https://url/to/archive/master.zip&visibility=<visibility>"

Uploads a blueprint to Cloudify’s manager. The call expects an “application/octet-stream” content type where the content is a zip/tar.gz/bz2 archive. It is possible to upload a blueprint from a URL by specifying the URL in the blueprint_archive_url request body property.

URI Parameters

Request Body

Property Type Description
application_file_name string The main blueprint file name in the blueprint’s archive.
blueprint_archive_url string A URL the blueprint to be uploaded should be downloaded from by the manager.
visibility string Optional parameter, defines who can see the blueprint (default: tenant). Supported for Cloudify Manager 4.3 and above.

Valid visibility values are:

Response

A Blueprint resource.

List Blueprints

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/blueprints?_include=id"
# Using CloudifyClient
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v3.1/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    },
    {
      "id": "hello-world-2"
    },
    {
      "id": "hello-world-3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

GET "{manager-ip}/api/v3.1/blueprints"

Lists all blueprints.

Response

Field Type Description
items list A list of Blueprint resources.

Delete Blueprint

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/blueprints/<blueprint-id>?force=false"
# Using CloudifyClient
client.blueprints.delete(blueprint_id='<blueprint-id>', force=False)

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>?force=false'
headers = {'Tenant': '<manager-tenant>'}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T13:35:13.971Z",
  "updated_at": "2017-04-19T13:35:13.971Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "tenant",
  "plan": {
    ...
  },
  "id": "hello-world"
}

DELETE "{manager-ip}/api/v3.1/blueprints/{blueprint-id}"

Deletes a specific blueprint.

URI Parameters

Property Type Description
blueprint_id string The id of the blueprint to delete.
force bool Delete the blueprint, even if there are blueprints that are currently using it. Supported for Cloudify Manager 4.5.5 and above.

Response

A Blueprint resource.

Download Blueprint

Downloads a specific blueprint as an archive.

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/archive" > <blueprint-archive-filename>.tar.gz
# Using CloudifyClient
client.blueprints.download(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<blueprint-archive-filename>.tar.gz', 'wb') as blueprint_archive:
    blueprint_archive.write(response.content)

GET "{manager-ip}/api/v3.1/blueprints/{blueprint-id}/archive"

URI Parameters

Response

The blueprint as an archive using an application/octet-stream content type.

Set Global Blueprint

Request Example

$ curl -X PATCH -H "Content-Type: application/json" -H "tenant: <tenant-name>"
    -u user:password "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/set-global"
# Python Client
client.blueprints.set_global('<blueprint-id>')

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Cloudify's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T10:56:06.267Z",
  "updated_at": "2017-04-19T10:56:06.267Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "global",
  "plan": {
    ...
  },
  "id": "hello-world"
}

PATCH "{manager-ip}/api/v3.1/blueprints/{blueprint-id}/set-global"

Set the blueprint’s visibility to global. Will be deprecated soon. For Cloudify Manager 4.3 and above, use ‘set-visibility’.

URI Parameters

Response

A Blueprint resource.

Set Blueprint Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/set-visibility"
# Python Client
client.blueprints.set_visibility('<blueprint-id>', '<visibility>')

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Cloudify's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T10:56:06.267Z",
  "updated_at": "2017-04-19T10:56:06.267Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "global",
  "plan": {
    ...
  },
  "id": "hello-world"
}

PATCH "<manager-ip>/api/v3.1/blueprints/{blueprint-id}/set-visibility"

Update the visibility of the blueprint. Supported for Cloudify Manager 4.3 and above.

URI Parameters

Request Body

Property Type Description
visibility string Defines who can see the blueprint. (Required)

Valid values are tenant or global.

Response

A Blueprint resource.

Cluster

The ManagerItem resource

The ManagerItem resource represents a node in the cluster

Attributes:

Attribute Type Description
id number The id of the manager in the cluster.
hostname string The hostname of this node.
private_ip string The internal IP of the manager used for internal communication.
public_ip string The externally accessible IP of this node.
version string Cloudify version of the node.
edition string Cloudify edition: community / premium / spire.
distribution string Distribution of the OS the node is running on.
distro_release string Distribution release of the OS the node is running on.
fs_sync_node_id string Syncthing node ID used for FS replication.
networks dict A dictionary of the networks associated with the node.
ca_cert_content string CA certificate used by the manager.

List Cluster Nodes

Request Example

client.manager.get_managers()
$ curl --header -u user:password "http://<manager-ip>/api/v3.1/managers"

Response Example

{
    "items":
    [
        {
            "id": 0,
            "hostname": "node1.openstack.local",
            "private_ip": "172.20.0.2",
            "public_ip": "191.31.72.16",
            "version": "5.0.0",
            "edition": "premium",
            "distribution": "centos",
            "distro_release": "core",
            "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
            "networks": {
                "default": "172.20.0.2",
                "network_2": "174.40.0.4"
            },
            "ca_cert_content": "CERT CONTENT"
        }
    ]
}

GET "{manager-ip}/api/v3.1/managers"

Lists all nodes in the cluster.

Response

Field Type Description
items list A list of ManagerItem resources

Get Cluster Node

Request Example

client.manager.get_managers("<hostname>")
$ curl --header -u user:password "http://<manager-ip>/api/v3.1/managers/<hostname>"

Response Example

{
    "id": 0,
    "hostname": "node1.openstack.local",
    "private_ip": "172.20.0.2",
    "public_ip": "191.31.72.16",
    "version": "5.0.0",
    "edition": "premium",
    "distribution": "centos",
    "distro_release": "core",
    "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
    "networks": {
        "default": "172.20.0.2",
        "network_2": "174.40.0.4"
    },
    "ca_cert_content": "CERT CONTENT"
}

GET "{manager-ip}/api/v3.1/managers/{hostname}"

Fetches the details of a node in the cluster.

URI Parameters

Response

A ManagerItem resource.

Delete Cluster Node

Request Example

client.manager.remove_manager("<hostname>")
$ curl -X DELETE -u user:password "http://<manager-ip>/api/v3.1/managers/<hostname>"

Response Example

{
    "id": 0,
    "hostname": "node1.openstack.local",
    "private_ip": "172.20.0.2",
    "public_ip": "191.31.72.16",
    "version": "5.0.0",
    "edition": "premium",
    "distribution": "centos",
    "distro_release": "core",
    "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
    "networks": {
        "default": "172.20.0.2",
        "network_2": "174.40.0.4"
    },
    "ca_cert_content": "CERT CONTENT"
}

DELETE "{manager-ip}/api/v3.1/managers/{hostname}"

Removes a node from the cluster. The node disconnects from the cluster and disables all cluster mechanisms. You can rejoin it to the cluster. The node is still connected to the DB of the cluster so it is highly recommended to dispose of it once removed. Only admin users can execute this operation.

URI Parameters

Response

A ManagerItem resource representing the node that was removed from the cluster.

Deployments

The Deployment Resource

Attributes:

Attribute Type Description
blueprint_id string The id of the blueprint the deployment is based on.
created_at datetime The time when the deployment was created.
created_by string The name of the user that created the deployment.
description string Deployment description.
groups object A dictionary containing the groups definition of deployment.
id string A unique identifier for the deployment.
inputs object A dictionary containing key value pairs which represents a deployment input and its provided value.
outputs object A dictionary containing an outputs definition of a deployment.
capabilities object A dictionary containing an capabilities definition of a deployment. Supported for Cloudify Manager 4.5.5 and above.
site_name string The name of the site the deployment is assigned to. Supported for Cloudify Manager 5.0 and above.
policy_triggers object A dictionary containing policy triggers of a deployment.
policy_types object A dictionary containing policies of a deployment.
tenant_name string The name of the tenant that owns the deployment.
updated_at datetime The time the deployment was last updated at.
workflows list A list of workflows that can be executed on a deployment.

List Deployments

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployments?_include=id"
# Using CloudifyClient
deployments = client.deployments.list(_include=['id'])
for deployment in deployments:
  print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello1"
    },
    {
      "id": "hello2"
    },
    {
      "id": "hello3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployments"

Lists all deployments.

Response

Field Type Description
items list A list of Deployment resources.

Get Deployment

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments?id=<deployment-id>&_include=id"
# Using CloudifyClient
client.deployments.get(deployment_id='<deployment-id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<deployment-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployments?id={deployment-id}"

Gets a deployment.

URI Parameters

Response

A Deployment resource.

Create Deployment

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}, "visibility": "<visibility>", "site_name": "<site name>"}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>?_include=id"
# Using CloudifyClient
client.deployments.create(
    blueprint_id='<blueprint-id>',
    deployment_id='<deployment-id>',
    inputs={...},
    visibility='<visibility>',
    site_name='<site name>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'blueprint_id': '<blueprint-id>',
    'inputs': {...},
    'visibility': '<visibility>',
    'site_name': '<site name>'
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "id": "hello4"
}

PUT -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}}' "{manager-ip}/api/v3.1/deployments/{deployment-id}"

Creates a new deployment.

URI Parameters

Request Body

Property Type Description
blueprint_id string The id of the blueprint the new deployment will be based on (required).
inputs object The dictionary containing key value pairs which represents the deployment inputs.
site_name string The name of the site to assign the new deployment to. Supported for Cloudify Manager 5.0 and above.
private_resource boolean Optional parameter, if set to True the uploaded resource will only be accessible by its creator. Otherwise, the resource is accessible by all users that belong to the same tenant (default: False).
skip_plugins_validation boolean Optional parameter, determines whether to validate if the required deployment plugins exist on the manager (default: False).
visibility string Optional parameter, defines who can see the deployment (default: tenant). Supported for Cloudify Manager 4.3 and above.

Valid visibility values are:

Response

A Deployment resource.

Delete Deployment

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>?_include=id&delete_logs=True"
# Using CloudifyClient
client.deployments.delete(deployment_id='<deployments-id>',
                          with_logs=False)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>'
headers = {'content-type': 'application/json'}
querystring = {
    'delete_logs': True
}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "hello4"
}

DELETE "{manager-ip}/api/v3.1/deployments/{deployment-id}"

Deletes a deployment.

An error is raised if the deployment has any live node instances. In order to ignore this validation, the ignore_live_nodes argument in request body can be used.

URI Parameters

Request Body

Property Type Description
ignore_live_nodes boolean Specifies whether to ignore the live nodes validation.

Response

A Deployment resource.

Set Deployment Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/set-visibility"
# Python Client
client.deployments.set_visibility('<deployment-id>', '<visibility>')

Response Example

{
  "inputs": {
    ...
  },
  "permalink": null,
  "description": "deployment_1",
  "blueprint_id": "blueprint_1",
  "policy_types": {
    ...
  },
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "updated_at": "2017-12-17T09:29:20.750Z",
  "created_by": "admin",
  "policy_triggers": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "groups": {
    ...
  },
  "workflows": {
    ...
  },
  "id": "deployment_1",
  "outputs": {
    ...
  }
}

PATCH "<manager-ip>/api/v3.1/deployments/{deployment-id}/set-visibility"

Update the visibility of the deployment. Supported for Cloudify Manager 4.3 and above.

URI Parameters

Request Body

Property Type Description
visibility string Defines who can see the deployment. (Required)

Valid values are tenant or global. global is supported for Cloudify Manager 4.5.5 and above.

Response

A Deployment resource.

Set Deployment Site

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"site_name": "<site name>"}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/set-site"
# Python Client
client.deployments.set_site('<deployment-id>', site_name='<site name'>, detach_site=False)

Response Example

{
  "inputs": {
    ...
  },
  "permalink": null,
  "description": "deployment_1",
  "blueprint_id": "blueprint_1",
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "updated_at": "2017-12-17T09:29:20.750Z",
  "created_by": "admin",
  "site_name": "a site name",
  "private_resource": false,
  "visibility": "tenant",
  "groups": {
    ...
  },
  "workflows": {
    ...
  },
  "id": "deployment_1",
  "outputs": {
    ...
  }
}

POST "<manager-ip>/api/v3.1/deployments/{deployment-id}/set-site"

Update the site of the deployment. Supported for Cloudify Manager 5.0 and above.

URI Parameters

Request Body

Property Type Description
site_name string The site name to assign the deployment.
detach_site Boolean Clear site relation from the deployment.

Response

A Deployment resource.

The Deployment Update Resource

Attributes:

Attribute Type Description
id string A unique identifier for the deployment update.
deployment_id string The id of the deployment.
old_blueprint_id string The id of the deployment’s blueprint before the update.
new_blueprint_id string The id of the deployment’s blueprint after the update.
old_inputs string The inputs of the deployment before the update.
new_inputs string The inputs of the deployment after the update.
state string The state of this update (“updating”, “executing_workflow”, “finalizing”, “successful”, “failed”, or “preview”).
tenant_name string The name of the tenant the deployment belongs to.
created_at datetime The time when the deployment update was started.
created_by string The name of the user that started the deployment update.
execution_id string The id of the execution performing the update.
private_resource boolean Is the deployment private.
visibility string The visibility of the deployment.
resource_availability string The availability of the deployment.
deployment_update_nodes object The list of the nodes in the deployment update.
deployment_update_node_instances object A dict containing the node instances in the deployment update.
modified_entity_ids object A dict containing the modified entities.
steps object The list of deployment update steps.
deployment_plan object A dict of the deployment plan.
deployment_update_deployment object A dict of the raw deployment.
central_plugins_to_install list A list of the plugins that are executed by the central deployment agent and will be installed.
central_plugins_to_uninstall list A list of the plugins that are executed by the central deployment agent and will be uninstalled.

Update Deployment

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"skip_install": "<skip_install>", "skip_uninstall": "<skip_uninstall>", "skip_reinstall": "<skip_reinstall>", "force": "<force>", "ignore_failure": "<ignore_failure>", "install_first": "<install_first>", "blueprint_id": "<blueprint_id>", "inputs": "<inputs>", "reinstall_list": "<reinstall_list>", "update_plugins": "<update_plugins>"}' \
    "http://<manager-ip>/api/v3.1/deployment-updates/<deployment-id>/update/initiate"
# Python Client
client.deployment_updates.update_with_existing_blueprint(skip_install="<skip_install>", skip_uninstall="<skip_uninstall>", skip_reinstall="<skip_reinstall>", force="<force>", ignore_failure="<ignore_failure>", install_first="<install_first>", blueprint_id="<blueprint_id>", inputs="<inputs>", reinstall_list="<reinstall_list>")

Response Example

{
  "old_inputs": {
    ...
  },
  "new_inputs": {
    ...
  },
  "state": "successful",
  "deployment_id": "deployment_1",
  "old_blueprint_id": "blueprint_1",
  "new_blueprint_id": "blueprint_2",
  "steps": [
    ...
  ],
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "created_by": "admin",
  "execution_id": "f92754a0-4cf4-4baa-80d3-0602f03f2b91",
  "deployment_update_deployment": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "resource_availability": "tenant",
  "modified_entity_ids": {
    ...
  },
  "deployment_plan": {
    ...
  },
  "id": "deployment_1-b22cd6b3-6dc1-4215-b9c0-404155eea939",
  "deployment_update_node_instances": {
    ...
  }
  "deployment_update_nodes": [
    ...
  ],
  "central_plugins_to_install": [
    ...
  ],
  "central_plugins_to_uninstall": [
    ...
  ]
}

PUT "<manager-ip>/api/v3.1/deployment-updates/<deployment-id>/update/initiate"

Update the deployment. Supported for Cloudify Manager 4.4 and above.

URI Parameters

Request Body

Property Type Description
blueprint_id string The id of the blueprint to use for the update
skip_install boolean Determines whether to skip installing node instances in update workflow
skip_install boolean Determines whether to skip uninstalling node instances in update workflow
skip_reinstall boolean Determines whether to reinstall the node instances whose properties or operations are modified in the deployment update
force boolean Force running update even if previous update failed
ignore_failure boolean Ignore operation failures while unisntalling node instances in update workflow
install_first boolean Install new node instances before reinstalling removed ones (default: first uninstall, then install)
inputs object Dictionary containing inputs to update in the deployment
reinstall_list object List of IDs for node instances to reinstall (even if skip_reinstall is true)
preview boolean If set, does not perform the update and returns the steps this update would make (default: False). Supported for Cloudify Manager 5.0 and above.

Response

A Deployment Update resource.

Get Deployment-Update

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployment-updates/<deployment-update-id>?_include=id"
# Using CloudifyClient
deployment_update = client.deployment_updates.get(update_id)

Response Example

{
  "old_inputs": {
    ...
  },
  "new_inputs": {
    ...
  },
  "state": "successful",
  "deployment_id": "deployment_1",
  "old_blueprint_id": "blueprint_1",
  "new_blueprint_id": "blueprint_2",
  "steps": [
    ...
  ],
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "created_by": "admin",
  "execution_id": "f92754a0-4cf4-4baa-80d3-0602f03f2b91",
  "deployment_update_deployment": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "resource_availability": "tenant",
  "modified_entity_ids": {
    ...
  },
  "deployment_plan": {
    ...
  },
  "id": "deployment_1-b22cd6b3-6dc1-4215-b9c0-404155eea939",
  "deployment_update_node_instances": {
    ...
  }
  "deployment_update_nodes": [
    ...
  ],
  "central_plugins_to_install": [
    ...
  ],
  "central_plugins_to_uninstall": [
    ...
  ]
}

GET "{manager-ip}/api/v3.1/deployment-updates/<deployment-update-id>"

Get a deployment update. Supported for Cloudify Manager 4.4 and above.

Response

A Deployment Update resource.

List Deployment Updates

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployment-updates?_include=id"
# Using CloudifyClient
deployment_updates = client.deployment_updates.list(
        sort=sort_by,
        is_descending=descending,
        _all_tenants=all_tenants,
        _search=search,
        _offset=pagination_offset,
        _size=pagination_size,
        deployment_id=deployment_id
    )

Response Example

{
  "items": [
    {
      "id": "update1"
    },
    {
      "id": "update2"
    },
    {
      "id": "update3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployment-updates"

Lists deployment updates. Supported for Cloudify Manager 4.4 and above.

Response

Field Type Description
items list A list of Deployment Update resources.

Get Deployment Outputs

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/outputs"
# Using CloudifyClient
client.deployments.outputs.get(deployment_id='<deployment-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>/outputs'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "deployment_id": "dep", 
  "outputs": {
    "output_1": "node_vbs4o4",
    "output_2": "some_value"
  }
}

GET "{manager-ip}/api/v3.1/deployments/{deployment-id}/outputs"

Gets deployment outputs.

URI Parameters

Response

A DeploymentOutput resource.

Get Deployment Capabilities

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/capabilities"
# Using CloudifyClient
client.deployments.capabilities.get(deployment_id='<deployment-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>/capabilities'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "deployment_id": "dep", 
  "capabilities": {
    "capability_1": "node_vbs4o4",
    "capability_2": "some_capability"
  }
}

GET "{manager-ip}/api/v3.1/deployments/{deployment-id}/capabilities"

Gets deployment capabilities. Supported for Cloudify Manager 4.5.5 and above.

URI Parameters

Response

A DeploymentOutput resource.

Events

The Event Resource

Attributes:

Attribute Type Description
blueprint_id string Blueprint id
deployment_id string Deployment id
error_causes [ErrorCause] List of errors that happened while executing a given task (only for cloudify_event items)
event_type string Event type name (only for cloudify_event items)
execution_id string Execution id
level string Log level (only for cloudify_log items)
logger string Logger id (only for cloudify_log items)
message string Message text
node_instance_id string Node instance id
node_name string Node name
operation string Operation path (only available in operation events)
reported_timestamp ISO 8601 The time at which the event occurred on the executing machine
timestamp ISO 8601 The time at which the event was logged on the management machine
type string Indicates whether the resource is a cloudify_event or a cloudify_log
workflow_id string Workflow id

The ErrorCause object

Attribute Type Description
message string Error message
traceback string Stack trace at the point where the exception was raised
type string Exception type

List events

Lists all events

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u user:<manager-password> \
    "http://<manager_ip>/api/v3.1/events"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')
events = client.events.list(include_logs=True)
for event in events:
    print event

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3.1/events'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(url, auth=HTTPBasicAuth('user', '<manager-password>'), headers=headers)
response.json()

Response Example

{
  "items": [
    {
      "node_instance_id": "vm_ke9e2d",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:42:00.484Z",
      "message": "Successfully configured cfy-agent",
      "level": "info",
      "node_name": "vm",
      "workflow_id": "install",
      "reported_timestamp": "2017-03-22T11:41:59.169Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_log",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387",
      "logger": "22e710c6-18b8-4e96-b8a3-2104b81c5bfc"
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_succeeded",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:42:00.788Z",
      "message": "Task succeeded 'cloudify_agent.installer.operations.create'",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": null,
      "reported_timestamp": "2017-03-22T11:42:00.083Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387"
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_failed",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:43:02.132Z",
      "message": "Task failed 'cloudify_agent.installer.operations.create' -> ERROR_MESSAGE",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": [
        {
          "message": "ERROR_MESSAGE",
          "traceback": "Traceback (most recent call last):\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 624, in main\n
  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 389, in handle\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/t
estmockoperations/tasks.py\", line 476, in execution_logging\n    raise NonRecoverableError('ERROR_MESSAGE', causes=causes)\nNonRecoverableError: ERROR_MESSAGE\n",
          "type": "NonRecoverableError"
        }
      ],
      "reported_timestamp": "2017-03-22T11:43:01.823Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 10000
    }
  }
}

GET "{manager-ip}/api/v3.1/events"

List events within a time range

GET "{manager-ip}/api/v3.1/events?_range=timestamp,[time_start],[time_end]"

Parameter Type Description
time_start ISO 8601 optional value to begin range with.
time_end ISO 8601 optional value to end range with.

all events within a time range:

GET "/api/v3.1/events?_range=timestamp,<time_start>,<time_end>"

all events since a given time:

GET "/api/v3.1/events?_range=timestamp,<time_start>,

all events until a given time:

GET "/api/v3.1/events?_range=timestamp,,<time_end>"

List events with filters

GET "{manager-ip}/api/v3.1/events?<filter>"

Allowed filters:

Multiple filters can be passed in the same request:

Response

Field Type Description
items list A list of Event resources.
metadata object Pagination metadata

Executions

The Execution Resource

Attributes:

Attribute Type Description
blueprint_id string The id of the blueprint the execution is in the context of.
created_at datetime The time the execution was queued at.
ended_at datetime The time the execution ended in successful, failed or cancelled state. Supported for Cloudify Manager 4.4 and above.
created_by string The name of the user that created the execution.
deployment_id string The id of the deployment the execution is in the context of.
error string The execution’s error message on execution failure.
id string A unique identifier for the execution.
is_system_workflow boolean true if the execution is of a system workflow.
parameters object A dict of the workflow parameters passed when starting the execution.
status string The executions status.
tenant_name string The name of the tenant that owns the execution.
workflow_id string The id/name of the workflow the execution is of.
started_at datetime The time the execution was started at. Supported for Cloudify Manager 4.5 and above.
scheduled_for datetime The time this execution is scheduled to start at. Supported for Cloudify Manager 4.5.5 and above.

List Executions

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/executions?_include=id
# Using CloudifyClient
executions = client.executions.list(_include=['id'])
for execution in executions:
  print execution

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

Response Example

{
  "items": [
    {
      "id": "dab3d7ac-fef0-4b8b-912f-5611cc8f20b5"
    },
    {
      "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/executions"

Lists all executions.

Response

Field Type Description
items list A list of Execution resources.

Get Execution

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"
# Using CloudifyClient
client.executions.get(execution_id='<execution_id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution_id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
}

GET "{manager-ip}/api/v3.1/executions/{execution-id}"

Gets an execution.

URI Parameters

Response

An Execution resource.

Start Execution

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "<deployment-id>", "workflow_id": "install"}' \
    "http://<manager_ip>/api/v3.1/executions?_include=id"
# Using CloudifyClient
client.executions.start(deployment_id='<deployment-id>', workflow_id='install')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'deployment_id': '<deployment-id>',
    'workflow_id': 'install',
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response example

{
  "id": "33dd51d4-5e24-4034-8ed6-2150cdbd98f7"
}

POST -d '{"deployment_id":{deployment-id}, "workflow_id":"<workflow-id>"}' "{manager-ip}/api/v3.1/executions"

Starts an execution.

Request Body

Property Type Description
workflow_id string The workflow id/name to execute.
deployment_id string The id of the deployment the workflow should be executed on.
allow_custom_parameters boolean Specifies whether to allow custom parameters, which are not present in the parameters schema of the workflow, to be passed when starting the execution (default=false).
parameters object A dictionary containing parameters to be passed to the execution when starting it.
force boolean Specifies whether to force the workflow execution in a case where there is already a running execution in the context of the same deployment or system wide workflow (default=false).
queue boolean If set, executions that can`t currently run will be queued and run automatically when possible. Supported for Cloudify Manager 4.5 and above.
schedule string The time (including timezone) this workflow will be executed at; expected format: YYYYMMDDHHMM+HHMM or YYYYMMDDHHMM-HHMM. i.e: 201801032230-0500 (Jan-03-18 10:30pm EST). Supported for Cloudify Manager 4.5.5 and above.

Response

An Execution resource.

Cancel Execution

Request Example

curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "dep", "action": "cancel"}'
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"
# Using CloudifyClient
client.executions.cancel(execution_id='<execution-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'deployment_id': 'dep', 'action': 'cancel'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "e7821510-c536-47f3-8fe7-691a91dc91ff"
}

POST -d '{"deployment_id":{deployment-id}, "action":"<action-method>"}' "{manager-ip}/api/v3.1/executions/{execution-id}"

Cancels an execution.

If passing cancel as the action fails to cancel the execution, force-cancel can be passed which will then kill the process running the execution.

URI Parameters

Request Body

Property Type Description
action string The cancellation method to perform: cancel or force-cancel

Response

An Execution resource.

Update Execution

Request Example

curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"status": "cancelled"}' \
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"
# Using CloudifyClient
client.executions.update(execution_id='<execution_id>', status='cancelled')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'status': 'cancelled'}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "21236984-9d1f-445e-8bca-f923175441f1"
}

PATCH "{manager-ip}/api/v3.1/executions/{execution-id}"

Updates an execution.

URI Parameters

Request Body

Property Type Description
status string The new status of the execution.

Response

An Execution resource.

License

Supported for Cloudify Manager 4.6 and above.

The License Resource

Attributes:

Attribute Type Description
id string A unique identifier for the license.
customer_id string The id of the customer the license was issued for.
expiration_date datetime The expiration date of the license.
license_edition string The edition of the license (Spire/ Premium)
trial boolean true if the license is a trial license.
cloudify_version string The maximal Cloudify version the license is valid for
capabilities object A list of capabilities the license supports.
expired boolean true if the license has expired.

Upload License

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    --data-binary @/<license_path>
    "<manager-ip>/api/v3.1/license"
# Using CloudifyClient
license = client.license.upload(license_path)

# Using requests
url = 'http://<manager-ip>/api/v3.1/license'
headers = {'Tenant': '<manager-tenant>',
           'Content-Type': 'application/json'}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)

Response Example

{
"expiration_date": "2018-11-24T00:00:00.000Z",
"cloudify_version": "4.6",
"license_edition": "Spire",
"capabilities": [
    "Mock1",
     "Mock2"
     ],
"trial": false,
"customer_id": "CloudifyMock",
"expired": true
}

PUT "{manager-ip}/api/v3.1/license"

Upload a license.

Response

A License resource.

List License

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/license"
# Using CloudifyClient
license = client.license.list()

# Using requests
url = 'http://<manager-ip>/api/v3.1/license'
headers = {'Tenant': '<manager-tenant>'
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)

Response Example

{
   "items":[
      {
         "expiration_date":"2018-11-24T00:00:00.000Z",
         "cloudify_version":"4.6",
         "license_edition":"Spire",
         "capabilities":[
            "Mock1",
            "Mock2"
         ],
         "trial":false,
         "customer_id":"CloudifyMock",
         "expired":true
      }
   ],
   "metadata":{
      "pagination":{
         "total":1,
         "offset":0,
         "size":1000
      }
   }
}

GET "{manager-ip}/api/v3.1/license"

List license.

Response

Field Type Description
items list A License resource.

Manager

The following REST API calls provide information about Cloudify’s manager.

Status

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/status"
# Using ClodifyManager
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'status'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "status": "running"
}

GET "{manager-ip}/api/v3.1/status"

Gets Cloudify manager status.

Attributes:

Attribute Type Description
status string The status of the manager. Will always have a “running” value.
services list List of Service resources each, representing a service running in the manager.

The Service Object:

Attribute Type Description
instances list List of Instance resources representing the instances of a service running in a manager in a DBus structure.
display_name string The service name.

The Instance Object:

Attribute Type Description
LoadState string Contains a state value that reflects whether the configuration file of this unit has been loaded.
Description string The description of the service instance.
state string The state of the service instance (unknown, down, up, finish).
MainPID integer The process id of the main service instance process.
Id string The id of the service instance.
ActiveState string Contains a state value that reflects whether the unit is currently active or not. The following states are currently defined: active, reloading, inactive, failed, activating, deactivating.
SubState string Encodes states of the same state machine that ActiveState covers, but knows more fine-grained states that are unit-type-specific.

Information about the instance fields can be found in the DBus reference.

Version

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/version?_include=version"
# Using CloudifyClient
client.manager.get_version()

# Using requests
url = 'http://<manager-ip>/api/v3.1/version'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'version'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "version": "4.0.1"
}

GET "{manager-ip}/api/v3.1/version"

Gets Cloudify manager version information.

Attributes:

Attribute Type Description
date ISO 8601 The date and time of the build the manager was built of.
commit string Git commit hash of the REST service code base used by the manager.
version string The version of Cloudify manager.
build string Build number.
edition string Software edition (either community or premium)

Node Instances

The NodeInstance Resource

Attributes:

Attribute Type Description
created_by string The name of the user that created the node instance.
deployment_id string The id of the deployment the node instance belongs to.
host_id string The Compute node instance id the node is contained within.
id string The id of the node instance.
relationships list The relationships the node has with other nodes.
runtime_properties object The runtime properties of the node instance.
state string The node instance state.
tenant_name string The name of the tenant that owns the node instance.
version integer A version attribute used for optimistic locking when updating the node instance.

List Node Instances

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/node-instances&_include=id"
# Using CloudifyClient
instances = client.node_instances.list(_include=['id'])
for instance in instances:
    print instance

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server_tfq3nt"
    },
    {
      "id": "vm_m7nmd7"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/node-instances"

Lists all node instances.

Response

Field Type Description
items list A list of NodeInstance resources.

Get Node Instance

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>&_include=id"
# Using CloudifyClient
client.node_instances.get('http_web_server_tfq3nt', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "http_web_server_tfq3nt"
}

GET "{manager-ip}/api/v3.1/node-instances/{node-instance-id}"

Gets a node instance.

URI Parameters

Response

A NodeInstance resource.

Update Node Instance

Requests Example

$ curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"version": 0, "runtime_properties": {"key": "value"}}' \
    "http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>?_include=id,runtime_properties"
# Using CloudifyClient
client.node_instances.update(
    node_instance_id='<node-instance-id>',
    version=0,
    runtime_properties={'key': 'value'},
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager_tenant>',
}
querystring = {'_include': 'id,runtime_properties'}
payload = {'version': 0, 'runtime_properties': {'key': 'value'}}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "runtime_properties": {
    "key": "value"
  },
  "id": "http_web_server_tfq3nt"
}

PATCH "{manager-ip}/api/v3.1/node-instances/{node-instance-id}"

Updates a node instance.

URI Parameters

Request Body

Property Type Description
runtime_properties object A dictionary containing the updated runtime properties of the node instance.
state string The new state of the node instance.
version integer The node instance current version (used for optimistic locking).

Response

A NodeInstance resource.

Nodes

The Node Resource

Attributes:

Attribute Type Description
blueprint_id string The id of the blueprint the node belongs to.
deploy_number_of_instances integer Default number of instances on deploy.
deployment_id string The id of the deployment the node belongs to.
host_id string The Compute node name the node is contained within.
id string The name of the node.
max_number_of_instances integer Maximum number of instances.
min_number_of_instances integer Minimum number of instances.
number_of_instances integer The number of node instances the node has.
operations object The operations the node exposes.
planned_number_of_instances integer -
plugins_to_install list A list of required plugins to install in order to execute the node’s operations.
plugins list A list of plugins the node is using for executing its operations.
properties object The properties of the node.
relationships list The relationships the node has with other nodes.
tenant_name string The name of the tenant that owns the node.
type_hierarchy list The type hierarchy of the node (ancestors).
type string The type of the node.

List Nodes

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/nodes?_include=id"
# Using CloudifyClient
nodes = client.nodes.list(_include=['id'])
for node in nodes:
    print node

# Using request
url = 'http://<manager-ip>/api/v3.1/nodes'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server"
    },
    {
      "id": "vm"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/nodes"

Lists all nodes.

Response

Field Type Description
items list A list of Node resources.

Operations

The Operation Resource

# Include this code when using the Cloudify Python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>')

Represents a stored operation, as part of a tasks graph

Attributes:

Attribute Type Description
id string Unique identifier of this operation
name string Name of this operation
state string The state of this operation, eg. PENDING, SENT or SUCCEEDED
dependencies list IDs of the operations that this operation depends on
type string Type of this operation, eg. RemoteWorkflowTask, LocalWorkflowTask or SubgraphTask
parameters dict Parameters as serialized by the operation class, to be used when reconstructing the operation
tasks_graph string ID of the tasks graph this operation belongs to

List operations

Request Example

$ curl -u user:password "http://<manager-ip>/api/v3.1/operations?graph_id=123"
client.operations.list(graph_id)

Response Example

[
    {
        "id": "operation-id",
        "state": "PENDING",
        "dependencies": [],
        "type": "SubgraphTask",
        "name": "my-subgraph",
        "parameters": {}
    }
]

GET "{manager-ip}/api/v3.1/operations"

Lists operations. To be used when filtering by a tasks graph id. This is the primary method of bulk-requesting operations when resuming a workflow.

Query Parameters

Property Type Description
graph_id string Filter operations by this tasks graph

Create operation

Request Example

$ curl -u user:password -X PUT \
    -d '{"name": "abc", "graph_id": "123", "dependencies": [], "type": "RemoteWorkflowTask"}' \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"
client.operations.create(operation_id, graph_id, name, type, parameters, dependencies)

Response Example

{
    "id": "operation-id",
    "state": "PENDING",
    "dependencies": [],
    "type": "SubgraphTask",
    "name": "my-subgraph",
    "parameters": {}
}

PUT "{manager-ip}/api/v3.1/operations/{operation-id}" Creates a single operation. State defaults to PENDING. Note that instead of using this method, it is faster to create many operations in bulk while creating the tasks graph.

Request Body

Property Type Description
name string Name of the operation
graph_id string ID of the tasks graph this operation belongs to
state string The state of this operation, eg. PENDING, SENT or SUCCEEDED
dependencies list IDs of the operations that this operation depends on
type string Type of this operation, eg. RemoteWorkflowTask, LocalWorkflowTask or SubgraphTask
parameters dict Parameters as serialized by the operation class, to be used when reconstructing the operation

Update operation

Request Example

$ curl -u user:password -X PATCH \
    -d '{"state": "FAILED"}' \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"
client.operations.update(operation_id, state)

Response Example

{
    "id": "operation-id",
    "state": "FAILED",
    "dependencies": [],
    "type": "SubgraphTask",
    "name": "my-subgraph",
    "parameters": {}
}

PATCH "{manager-ip}/api/v3.1/operations/{operation-id}" Updates the state of an operation. Other attributes are immutable.

Request Body

Property Type Description
state string The state of this operation, eg. PENDING, SENT or SUCCEEDED

Delete operation

Request Example

$ curl -u user:password -X DELETE \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"
client.operations.delete(operation_id)

DELETE "{manager-ip}/api/v3.1/operations/{operation-id}" Deletes an operation. Note that operations which are terminated should still be stored in persistent storage, and should have their state updated to SUCCEEDED or FAILED rather than be deleted.

Plugins

The Plugin Resource

Attributes:

Attribute Type Description
archive_name string The plugin archive file name.
distribution_release string The OS distribution release name the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
distribution_version string The OS distribution version the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
distribution string The OS distribution the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
excluded_wheels list a list of wheels that were excluded from the plugin package.
id string The ID assigned to the plugin upon upload.
package_name string The python package name.
package_source string The python package source, i.e git, pip etc.
package_version string The python package version.
supported_platform string The supported platform for the plugin package, ‘any’ if the plugin is compatible with all platforms.
supported_py_versions list a list of python platforms supported by the plugin.
tenant_name string The name of the tenant that owns the plugin.
uploaded_at ISO 8601 The time and date the plugin was uploaded on to the Cloudify-Manager.
wheels list A list of wheels contained in the plugin package.

List Plugins

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins?_include=id"
# Using CloudifyClient
plugins = client.plugins.list(_include=['id'])
for plugin in plugins:
    print plugin

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
    },
    {
      "id": "f10a4970-6cfa-4b24-9cab-f85db93204e0"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/plugins"

Lists all plugins.

Response

Field Type Description
items list A list of Plugin resources.
metadata dict Metadata relevant to the list response.

Get Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>?_include=id"
# Using CloudifyClient
client.plugins.get(plugin_id='<plugin-id'>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
}

GET "{manager-ip}/api/v3.1/plugins/{plugin-id}"

Gets a plugin.

URI Parameters

Response

A Plugin resource.

Delete Plugin

Request Example

$ curl -X DELETE \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"force": false}' \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>?_include=id"
# Using CloudifyClient
client.plugins.delete(plugin_id='<plugin-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload = {'force': False}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

DELETE "{manager-ip}/api/v3.1/plugins/{plugin-id}"

Deletes a plugin from the Cloudify-Manager.

URI Parameters

Request Body

Property Default Description
force false Specifies whether to force plugin deletion even if there are deployments that currently use it.

Response

The deleted Plugin resource.

Upload Plugin

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins?plugin_archive_url=http://url/to/archive.wgn&_include=id&visibility=<visibility>"
# Using CloudifyClient
client.plugins.upload(plugin_path='http://url/to/archive.wgn',
                      visibility='<visibility>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'plugin_archive_url': 'http://url/to/archive.wgn',
    '_include': 'id',
    'visibility': '<visibility>'
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Example Response

{
  "id": "d80542f4-ec0c-4438-8a29-54cb9a904114"
}

POST "{manager-ip}/api/v3.1/plugins"

Upload a plugin

Request Body

Property Type Description
plugin_path string The plugin archive local path.
plugin_archive_url string A URL of the plugin archive to be uploaded. The plugin will be downloaded by the manager.
visibility string Optional parameter, defines who can see the plugin (default: tenant). Supported for Cloudify Manager 4.3 and above.

Valid visibility values are:

Response

The new uploaded Plugin resource.

Download Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>/archive" > <plugin-archive-filename>.wgn
# Using CloudifyClient
client.plugins.download(
   plugin_id='<plugin-id>',
   output_file='<plugin-archive-filename>',
)

# Using Requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<plugin-archive-filename>.wgn', 'wb') as plugin_archive:
    plugin_archive.write(response.content)

GET "{manager-ip}/api/v3.1/plugins/{plugin-id}/archive"

Downloads a plugin.

URI Parameters

Response

The requested plugin archive.

Set Global Plugin

Request Example

$ curl -X PATCH -H "Content-Type: application/json" -H "tenant: <tenant-name>"
    -u user:password "http://<manager-ip>/api/v3.1/plugins/<plugin-id>/set-global"
# Python Client
client.plugins.set_global(<plugin-id>)

Response Example

{
  "distribution_release": "core",
  "supported_py_versions": [
    "py27"
  ],
  "uploaded_at": "2017-10-19T14:19:39.727Z",
  "archive_name": "cloudify_openstack_plugin-2.0.1-py27-none-linux_x86_64-centos-Core.wgn",
  "package_name": "cloudify-openstack-plugin",
  "distribution_version": "7.0.1406",
  "tenant_name": "default_tenant",
  "excluded_wheels": [

  ],
  "created_by": "admin",
  "distribution": "centos",
  "package_source": "https://github.com/cloudify-cosmo/cloudify-openstack-plugin/archive/master.tar.gz",
  "private_resource": false,
  "visibility": "global",
  "supported_platform": "linux_x86_64",
  "package_version": "2.0.1",
  "wheels": [
    "keystoneauth1-2.19.0-py2.py3-none-any.whl",
    "python_novaclient-7.0.0-py2.py3-none-any.whl",
     ...
  ],
  "id": "c7f6757e-b48d-4c26-ab91-cfc8c1e4851c"
}

PATCH "{manager-ip}/api/v3.1/plugins/{plugin-id}/set-global"

Set the plugin’s visibility to global. Will be deprecated soon. For Cloudify Manager 4.3 and above, use ‘set-visibility’.

URI Parameters

Response

A Plugin resource.

Set Plugin Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>/set-visibility"
# Python Client
client.plugins.set_visibility('<plugin-id>', '<visibility>')

Response Example

{
  "distribution_release": "core",
  "supported_py_versions": [
    "py27"
  ],
  "uploaded_at": "2017-10-19T14:19:39.727Z",
  "archive_name": "cloudify_openstack_plugin-2.0.1-py27-none-linux_x86_64-centos-Core.wgn",
  "package_name": "cloudify-openstack-plugin",
  "distribution_version": "7.0.1406",
  "tenant_name": "default_tenant",
  "excluded_wheels": [

  ],
  "created_by": "admin",
  "distribution": "centos",
  "package_source": "https://github.com/cloudify-cosmo/cloudify-openstack-plugin/archive/master.tar.gz",
  "private_resource": false,
  "visibility": "global",
  "supported_platform": "linux_x86_64",
  "package_version": "2.0.1",
  "wheels": [
    "keystoneauth1-2.19.0-py2.py3-none-any.whl",
    "python_novaclient-7.0.0-py2.py3-none-any.whl",
     ...
  ],
  "id": "c7f6757e-b48d-4c26-ab91-cfc8c1e4851c"
}

PATCH "<manager-ip>/api/v3.1/plugins/{plugin-id}/set-visibility"

Update the visibility of the plugin. Supported for Cloudify Manager 4.3 and above.

URI Parameters

Request Body

Property Type Description
visibility string Defines who can see the plugin. (Required)

Valid values are tenant or global.

Response

A Plugin resource.

The Plugins Update Resource

Attributes:

Attribute Type Description
id string A unique identifier for the plugins update.
state string The state of this update (“updating”, “executing_workflow”, “finalizing”, “successful”, or “failed”).
blueprint_id string The id of the blueprint that its deployments will get their plugins updated.
temp_blueprint_id string The id of the temporary internal blueprint created for the purpose of this plugins update.
execution_id string The id of the plugins update execution.
deployments_to_update list A list of deployment IDs that are updated in this plugins update.
forced bool Whether or not this plugins update was executed regardless of other active/failed plugins updates.
created_at datetime The time when the plugins update was started.
created_by string The name of the user that started the plugins update.
tenant_name string The name of the tenant the plugins update belongs to.
visibility string The visibility of the plugins update.
private_resource boolean Is the plugins update private.
resource_availability string The availability of the plugins update.

Update Plugins

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"force": "<force>"}' \
    "<manager-ip>/api/v3.1/plugins-updates/<blueprint-id>/update/initiate"
# Python Client
client.plugins_update.update_plugins(blueprint_id="<blueprint_id>", force="<force>")

Response Example

{
 "forced": false,
 "blueprint_id": "baddd86fb-864b-483e-a98a-d53e2b728ccd",
 "tenant_name": "default_tenant",
 "created_at": "2019-07-10T07:24:40.520Z",
 "visibility": "tenant",
 "private_resource": false,
 "state": "executing_workflow",
 "temp_blueprint_id": "bbf4b172-3b21-460c-aed8-4f55b55f3b4f",
 "created_by": "admin",
 "deployments_to_update": [
    "dd7b03fb3-8f92-404c-8ddd-d81bd6a2bc9b"
 ],
 "resource_availability": "tenant",
 "id": "ce63a9d6-726b-4ff2-a267-f953af5dc32d",
 "execution_id": "8ec77e89-b418-4472-9b44-fe9d7a7fe163"
}

PUT "<manager-ip>/api/v3.1/plugins-updates/<blueprint-id>/update/initiate"

Update the plugins for that blueprint’s deployments. Supported for Cloudify Manager 5.0.0 and above.

URI Parameters

Request Body

Property Type Description
force boolean Specifies whether to force the plugin update regardless of other active/failed plugins updates state.

Response

A Plugins Update resource.

Get Plugins-Update

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/plugins-updates/<plugins-update-id>?_include=id"
# Using CloudifyClient
plugins_update = client.plugins_update.get(plugins_update_id=plugins_update_id)

Response Example

{
 "forced": false,
 "blueprint_id": "baddd86fb-864b-483e-a98a-d53e2b728ccd",
 "tenant_name": "default_tenant",
 "created_at": "2019-07-10T07:24:40.520Z",
 "visibility": "tenant",
 "private_resource": false,
 "state": "executing_workflow",
 "temp_blueprint_id": "bbf4b172-3b21-460c-aed8-4f55b55f3b4f",
 "created_by": "admin",
 "deployments_to_update": [
    "dd7b03fb3-8f92-404c-8ddd-d81bd6a2bc9b"
 ],
 "resource_availability": "tenant",
 "id": "ce63a9d6-726b-4ff2-a267-f953af5dc32d",
 "execution_id": "8ec77e89-b418-4472-9b44-fe9d7a7fe163"
}

GET "<manager-ip>/api/v3.1/plugins-updates/<plugins-update-id>"

Get a plugins update. Supported for Cloudify Manager 5.0.0 and above.

Response

A Plugins Update resource.

List Plugins Updates

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/plugins-updates?_include=id"
# Using CloudifyClient
plugins_updates = client.plugins_update.list(
        sort=sort_by,
        is_descending=descending,
        _all_tenants=all_tenants,
        _search=search,
        _offset=pagination_offset,
        _size=pagination_size,
        plugins_update_id=plugins_update_id
    )

Response Example

{
  "items": [
    {
      "id": "update1",
      ...
    },
    {
      "id": "update2",
      ...
    },
    {
      "id": "update3",
      ...
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/plugins-updates"

Lists the plugins updates. Supported for Cloudify Manager 5.0.0 and above.

Response

Field Type Description
items list A list of Plugins Update resources.

Secrets

The Secret Resource

A Secret resource is a key-value pair saved per tenant. A user can ensure all secrets (such as credentials to IaaS environments, passwords, etc) are kept in a secured manner, and adhere to isolation requirements between different tenants.

Attributes:

Attribute Type Description
created_at datetime The time when the secret was created.
key string The secret’s key, unique per tenant.
updated_at datetime The time the secret was last updated at.
value string The secret’s value.
visibility string Defines who can see the secret. Can be private, tenant or global. Supported for Cloudify Manager 4.3 and above.
is_hidden_value boolean Determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.

List Secrets

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/secrets"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "items": [
        {
            "created_at": "2017-11-24T10:42:29.756Z",
            "created_by": "admin",
            "key": "<secret_key>",
            "visibility": "tenant",
            "tenant_name": "default_tenant",
            "updated_at": "2017-11-24T10:42:29.756Z",
            "is_hidden_value": false
        }
    ],
    "metadata": {
        "pagination": {
            "offset": 0,
            "size": 0,
            "total": 1
        }
    }
}

GET "{manager_ip}/api/v3.1/secrets"

List all secrets.

Response

Field Type Description
items list A list of Secret resources without the secret’s value.

Get Secret

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/secrets/<secret_key>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.get(<secret_key>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2017-11-24T10:42:29.756Z",
    "created_by": "admin",
    "key": "<secret_key>",
    "private_resource": false,
    "visibility": "tenant",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T10:42:29.756Z",
    "value": "<secret_value>",
    "is_hidden_value": false
}

GET "{manager_ip}/api/v3.1/secrets/{secret_key}"

Retrieves a specific secret.

URI Parameters

Response

A Secret resource.

Create Secret

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"value": <new_secret_value>, "update_if_exists": false, "visibility": "<visibility>", "is_hidden_value": false}' \
    "http://<manager_ip>/api/v3.1/secrets/<new_secret_key>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.create(
    <new_secret_key>,
    <new_secret_value>,
    update_if_exists=False,
    visibility='<visibility>',
    is_hidden_value=False
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets/<new_secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'value': '<new_secret_value>',
    'update_if_exists': False,
    'visibility': '<visibility>',
    'is_hidden_value': False
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2017-11-24T10:42:29.756Z",
    "created_by": "admin",
    "key": "<new_secret_key>",
    "private_resource": false,
    "visibility": "tenant",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T10:42:29.756Z",
    "value": "<new_secret_value>",
    "is_hidden_value": false
}

PUT -d '{"value": <new_secret_value>}' "{manager_ip}/api/v3.1/secrets/{new_secret_key}"

Creates a secret.

URI Parameters

Request Body

Property Type Description
value string The secret’s value.
update_if_exists boolean Update value if secret already exists (optional, defaults to false).
visibility string Optional parameter, defines who can see the secret (default: tenant). Supported for Cloudify Manager 4.3 and above.
is_hidden_value boolean Optional parameter, determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.

Valid visibility values are:

Response

A Secret resource.

Update Secret

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"value": <new_secret_value>, "visibility": "<visibility>", "is_hidden_value": false}' \
    "http://<manager_ip>/api/v3.1/secrets/<secret_key>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.update(<secret_key>, <new_secret_value>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'value': '<new_secret_value>'}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2017-11-24T11:01:05.357Z",
    "created_by": "admin",
    "key": "<secret_key>",
    "private_resource": false,
    "visibility": "tenant",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T12:02:38.296Z",
    "value": "<new_secret_value>",
    "is_hidden_value": false
}

PATCH -d '{"value": <new_secret_value>, "visibility": <visibility>, "is_hidden_value": <is_hidden_value>}' "{manager_ip}/api/v3.1/secrets/{secret_key}"

Updates a secret.

URI Parameters

Request Body

Property Type Description
value string The secret’s new value.
visibility string Optional parameter, defines who can see the secret (default: tenant). Supported for Cloudify Manager 4.3 and above.
is_hidden_value boolean Optional parameter, determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.

Response

A Secret resource.

Delete Secret

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/secrets/<secret_key>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.delete(<secret_key>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2017-11-24T11:01:05.357Z",
    "created_by": "admin",
    "key": "<secret_key>",
    "private_resource": false,
    "visibility": "tenant",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T12:05:30.190Z",
    "value": "<secret_value>",
    "is_hidden_value": false
}

DELETE "{manager_ip}/api/v3.1/secrets/{secret_key}"

Deletes a secret.

URI Parameters

Response

A Secret resource.

Set Global Secret

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/secrets/<secret_key>/set-global"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.secrets.set_global(<secret_key>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/secrets/<secret_key>/set-global'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2017-11-24T12:10:49.789Z",
    "created_by": "admin",
    "key": "<secret_key>",
    "private_resource": false,
    "visibility": "global",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T12:11:16.495Z",
    "value": "<secret_value>",
    "is_hidden_value": false
}

PATCH "{manager_ip}/api/v3.1/secrets/{secret_key}/set-global"

Set the secret’s visibility to global. Will be deprecated soon. For Cloudify Manager 4.3 and above, use ‘set-visibility’.

URI Parameters

Response

A Secret resource.

Set Secret Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/secrets/<secret-key>/set-visibility"
# Python Client
client.secrets.set_visibility('<secret-key>', '<visibility>')

Response Example

{
    "created_at": "2017-11-24T12:10:49.789Z",
    "created_by": "admin",
    "key": "<secret-key>",
    "private_resource": false,
    "visibility": "global",
    "tenant_name": "default_tenant",
    "updated_at": "2017-11-24T12:11:16.495Z",
    "value": "<secret-value>",
    "is_hidden_value": false
}

PATCH "<manager-ip>/api/v3.1/secrets/{secret-key}/set-visibility"

Update the visibility of the secret. Supported for Cloudify Manager 4.3 and above.

URI Parameters

Request Body

Property Type Description
visibility string Defines who can see the secret. (Required)

Valid values are tenant or global.

Response

A Secret resource.

Export Secrets

Request Example

 $ curl -X GET \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/secrets/share/export?_passphrase=<passphrase>?non-encrypted=false"
# Python Client

client.secrets.export(_passphrase=<passphrase>)

# Using request
url = 'http://<manager-ip>/api/v3.1/secrets/share/export'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_passphrase': '<passphrase>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

[
    {"is_hidden_value": false,
     "tenant_name": "default_tenant",
     "visibility": "tenant",
     "value": "gAAAAABdEfLE3sdIzNRd1c0-_LlMn9YhNxjv8ZYlopi7suuayyW4IajlBAfFBUNYYOxoTJP1iTjAGhxangEFvkwLp14vmmiCZQ==",
     "key": "<secret_key>",
     "encrypted": true
     },
      {
      "is_hidden_value": false,
      "tenant_name": "default_tenant",
      "visibility": "tenant",
      "value": "gAAAAABdEfLERkwqzBuWNtBoK4ftN89LGd8pRP4XFirzlQdXVvMcWpCSuBgUZ_XapD9dffv91Ge7-1p8nzXZfB75YJAO5P-WbQ==",
      "key": "<secret_key>",
      "encrypted": true
      }
]

GET "<manager-ip>/api/v3.1/secrets/share/export"

Export secretes from the Manager to a file. Supported for Cloudify Manager 5.0 and above.

URI Parameters

Response

A list of Secret resources.

Import Secrets

    data = {
        'secrets_list': secrets_list,
        'tenant_map_dict': tenant_map_dict,
        'passphrase': passphrase,
        'override_collisions': override_collisions
    }

Request Example

 $ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"secrets_list": "<secrets_list>", "tenant_map_dict": "<tenant_map_dict>", "passphrase": "<passphrase>", "override_collisions": false}' \
    "http://<manager-ip>/api/v3.1/secrets/share/import"
# Python Client

client.secrets.import_secrets(secrets_list=<secrets_list>,
                              tenant_map_dict=<tenant_map_dict>,
                              passphrase=<passphrase>,
                              override_collisions=<override_collisions>)

POST "<manager-ip>/api/v3.1/secrets/share/import"

Import secrets from a file to the Manager. Supported for Cloudify Manager 5.0 and above.

Sites

Supported for Cloudify Manager 5.0 and above.

The Site Resource

A Site represents a container with a (typically) limited number of nodes. A site can be a mobile cell-tower, or it can be a small branch, or any other logical entity. Sites may be associated with a location which will allow a map view (widget is not available yet) and more advanced capabilities in the future. Sites may contain multiple deployments, which allows for easy grouping and filtering by site.

Attributes:

Attribute Type Description
name string The site’s name, unique per tenant.
location string The location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
visibility string Defines who can see the site. Can be private, tenant or global.
tenant_name string The name of the tenant that owns the site.
created_at datetime The time when the site was created.
created_by string The name of the user that created the site.

List Sites

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>'
)
client.sites.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "items": [
        {
            "created_at": "2019-06-12T10:52:45.858Z",
            "created_by": "admin",
            "location": "41.8333925, -88.0121478",
            "name": "Chicago",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        },
        {
            "created_at": "2019-06-12T10:53:06.968Z",
            "created_by": "admin",
            "location": "25.7823404, -80.3695441",
            "name": "Chicago",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        },
        {
            "created_at": "2019-06-12T10:53:32.838Z",
            "created_by": "admin",
            "location": "32.080327, 34.767420",
            "name": "Tel-Aviv",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        }
    ],
    "metadata": {
        "pagination": {
            "offset": 0,
            "size": 1000,
            "total": 3
        }
    }
}

GET "{manager_ip}/api/v3.1/sites"

List all sites.

Response

Field Type Description
items list A list of Site resources.

Get Site

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.get(<site_name>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2019-06-12T10:53:32.838Z",
    "created_by": "admin",
    "location": "32.080327, 34.767420",
    "name": "Tel-Aviv",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

GET "{manager_ip}/api/v3.1/sites/{site_name}"

Retrieves a specific site.

URI Parameters

Response

A Site resource.

Create Site

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"location": "<site_location>", "visibility": "<visibility>"}' \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.create(
    '<site_name>',
    location='<site_location>',
    visibility='<visibility>'
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'name': '<site_name>',
    'location': '<site_location>',
    'visibility': '<visibility>'
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2019-06-13T12:38:37.747Z",
    "created_by": "admin",
    "name": "Tel-Aviv",
    "location": "32.080327, 34.767420",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

PUT -d '{"location": "<site_location>", "visibility": "<visibility>"}' "{manager_ip}/api/v3.1/sites/{site_name}"

Creates a site.

URI Parameters

Request Body

Property Type Description
location string Optional parameter, the location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
visibility string Optional parameter, defines who can see the site (default: tenant)

Valid visibility values are:

Response

A Site resource.

Update Site

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"new_name": "<site_new_name>", "location": "<site_location>", "visibility": "<visibility>"}' \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.update(
    '<site_name>',
    location='<site_location>',
    visibility='<visibility>',
    new_name='<site_new_name>'
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'new_name': '<site_new_name>', 'location': '<site_location>', 'visibility': '<visibility>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2019-06-13T12:38:37.747Z",
    "created_by": "admin",
    "name": "Tel-Aviv",
    "location": "32.080327, 34.767420",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

POST -d '{"new_name": "<site_name>", "location": "<site_location>", "visibility": "<visibility>"}' "{manager_ip}/api/v3.1/sites/{site_name}"

Updates a site.

URI Parameters

Request Body

Property Type Description
new_name string Optional parameter, the new name of the site
location string Optional parameter, the location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
visibility string Optional parameter, defines who can see the site

Valid visibility values are:

Response

A Site resource.

Delete Site

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.delete(<site_name>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2019-06-13T12:38:37.747Z",
    "created_by": "admin",
    "name": "Tel-Aviv",
    "location": "32.080327, 34.767420",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

DELETE "{manager_ip}/api/v3.1/sites/{site_name}"

Deletes a site.

URI Parameters

Response

A Site resource.

Snapshots

The Snapshot Resource

Attributes:

Attribute Type Description
created_at ISO 8601 The time the snapshot was uploaded to or created on the manager.
error string Message of an error if snapshot creation failed.
id string A unique identifier of the snapshot.
status string Status of the snapshot. One of created/failed/uploading/uploaded.

List Snapshots

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots?_include=id"
# Using CloudifyClient
snapshots = client.snapshots.list(_include=['id'])
for snapshot in snapshots:
    print snapshot

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "snapshot1"
    },
    {
      "id": "snapshot2"
    },
    {
      "id": "snapshot3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/snapshots"

Lists all snapshots.

Response

Attribute Type Description
items list A list of Snapshot resources.

Create Snapshot

Requests Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>"
# Using CloudifyClient
client.snapshots.create(
    snapshot_id='<snapshot-id>',
    include_metrics=False,
    include_credentials=False,
)


# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "status": "pending",
  "parameters": {
    "include_metrics": false,
    "config": {
      "postgresql_db_name": "cloudify_db",
      "default_tenant_name": "default_tenant",
      "postgresql_bin_path": "/usr/pgsql-9.5/bin/",
      "failed_status": "failed",
      "postgresql_username": "cloudify",
      "db_port": 9200,
      "postgresql_password": "cloudify",
      "created_status": "created",
      "db_address": "localhost",
      "file_server_root": "/opt/manager/resources",
      "postgresql_host": "localhost"
    },
    "include_credentials": true,
    "snapshot_id": "snapshot4"
  },
  "is_system_workflow": true,
  "blueprint_id": null,
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T16:16:45.948Z",
  "created_by": "admin",
  "private_resource": false,
  "workflow_id": "create_snapshot",
  "error": "",
  "deployment_id": null,
  "id": "bb9cd6df-7acd-4649-9fc1-fe062759cde8"
}

PUT "{manager-ip}/api/v3.1/snapshots/{snapshot-id}"

Creates a new snapshot.

URI Parameters

Request Body

Property Type Description
include_metrics string Specifies whether metrics stored in InfluxDB should be included in the created snapshot (Default: true).
include_credentials string Specifies whether agent SSH keys (including those specified in uploaded blueprints) should be included in the created snapshot (Default: false).
include_logs string Specifies whether logs should be included in the created snapshot (Default: true). Supported for Cloudify Manager 4.3 and above.
include_events string Specifies whether events should be included in the created snapshot (Default: true). Supported for Cloudify Manager 4.3 and above.
queue boolean If set, snapshot-creation-workflow that can`t currently run will be queued and run automatically when possible. Supported for Cloudify Manager 4.5 and above.

Response

An Execution resource representing the create snapshot workflow execution.

Delete Snapshot

Requests Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>"
# Using CloudifyClient
client.snapshots.delete(snapshot_id='<snapshot-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Example Response

{
  "status": "uploaded",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T17:04:22.989Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "snapshot4"
}

DELETE "{manager-ip}/api/v3.1/snapshots/{snapshot-id}"

Deletes an existing snapshot.

URI Parameters

Response

An empty Snapshot resource, with one non-empty field (its id).

Restore Snapshot

Requests Example

curl -s -X POST \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"recreate_deployments_envs": true, "force": false, "restore_certificates": false, "no_reboot": false}' \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/restore"
# Using CloudifyClient
client.snapshots.restore(snapshot_id='<snapshot-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/restore'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {
    'recreate_deployments_envs': True,
    'force': False,
    'restore_certificates': False,
    'no_reboot': False
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Example Response

{
  "status": "pending",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T17:23:30.779Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "1cadbb76-4532-4eae-a139-80bff328944d"
}

POST "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/restore"

Restores the specified snapshot on the manager.

URI Parameters

Request Body

Property Default Description
force false Specifies whether to force restoring the snapshot on a manager that already contains blueprints/deployments.
recreate_deployments_envs true Specifies whether deployment environments should be created for restored deployments.
restore_certificates false Specifies whether to try and restore the certificates from the snapshot and use them to override the current Manager certificates, in the event that snapshot’s certificates metadata does not match the current Manager’s certificates metadata. Useful when there are live agents from the Manager from which the snapshot was created that you want to control with the current Manager. After execution the Manager will automatically reboot - unless the no_reboot property is True.
no_reboot false Only relevant when the restore_certificates property is True. Specifies whether to the automatic reboot at the end of the snapshot restore execution. It is not recommended to use this option since the Manager will not function well after certificates restore without a reboot. In that case, you must manually reboot the machine.

Response

An Execution resource representing the restore snapshot workflow execution.

Download Snapshot

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/archive" > <snapshot-archive-filename>.zip
# Using CloudifyClient
client.snapshots.download(
    snapshot_id='<snapshot-id>',
    output_file='<snapshot-archive-filename>.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<snapshot-archive-filename>.wgn', 'wb') as snapshot_archive:
    snapshot_archive.write(response.content)

GET "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/archive"

Downloads an existing snapshot.

URI Parameters

Response

A streamed response (content type application/octet-stream), which is a zip archive containing the snapshot data.

Upload Snapshot

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/archive?snapshot_archive_url=http://url/to/archive.zip"
# Using CloudifyClient
client.snapshots.upload(
    snapshot_id='<snapshot-id>',
    snapshot_path='http://url/to/archive.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/archive'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'snapshot_archive_url': 'http://url/to/archive.zip'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "status": "uploaded",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T18:13:25.912Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "snapshot5"
}

PUT "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/archive"

Uploads a snapshot to the Cloudify Manager. The call expects a application/octet-stream content type where the content is a zip archive. It is possible to upload a snapshot from a URL by specifying the URL in the snapshot_archive_url request body property.

URI Parameters

Request Body

Property Type Description
snapshot_archive_url string Optional parameter specifying a url to a snapshot that will be uploaded to the manager.

Response

A Snapshot resource.

Snapshot-Restore Status

Request Example

$ curl -X GET "http://<manager-ip>/api/v3.1/snapshot-status"
# Using CloudifyClient
client.snapshots.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshot-status'
response = requests.get(url)
response.json()

Response Example

{
  "status": "No `restore_snapshot` workflow currently running.",
}

GET "{manager-ip}/api/v3.1/snapshot-status"

This method returns the status of the restore_snapshot workflow (whether or not it’s in progress). Supported for Cloudify Manager 5.0.5 and above.

Summaries

The summary resource

Attributes:

Attribute Type Description
_target_field string The field to generate a summary on. Valid fields are listed for each sub-resource.
_sub_field string Optional sub-field to summarise on. Valid fields are identical to those for _target_field.

All attributes for filtering the specific resources are also supported, e.g. filtering blueprints by blueprint_id or filtering deployments by deployment_id. See documentation for each resource to find applicable filtering attributes.

Summarize Blueprints

Valid fields: tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/blueprints?_target_field=tenant_name&_all_tenants=true"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/blueprints?_target_field=tenant_name&_sub_field=visibility&_all_tenants=true"
# Using CloudifyClient
summaries = client.summary.blueprints.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/blueprints'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprints": 3,
      "tenant_name": "test1"
    },
    {
      "blueprints": 3,
      "tenant_name": "test2"
    },
    {
      "blueprints": 3,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

With sub-field

{
  "items": [
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "test1"
    },
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "test2"
    },
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/blueprints?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of blueprints based on the target field and optional sub-field.

Response

Field Type Description
items list A list of blueprint summaries based on the target field and optional sub-field.

Summarize Deployments

Valid fields: blueprint_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/deployments?_target_field=blueprint_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/deployments?_target_field=tenant_name&_sub_field=blueprint_id&_all_tenants=true"
# Using CloudifyClient
summaries = client.summary.deployments.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprint_id": "s",
      "deployments": 5
    },
    {
      "blueprint_id": "sga",
      "deployments": 2
    }
  ],
  "metadata": {
    "pagination": {
      "size": 1000,
      "total": 2,
      "offset": 0
    }
  }
}

With sub-field

{
  "items": [
    {
      "by blueprint_id": [
        {
          "blueprint_id": "s",
          "deployments": 1
        },
        {
          "blueprint_id": "sg",
          "deployments": 3
        },
        {
          "blueprint_id": "sga",
          "deployments": 5
        }
      ],
      "deployments": 9,
      "tenant_name": "test1"
    },
    {
      "by blueprint_id": [
        {
          "blueprint_id": "sga",
          "deployments": 1
        },
        {
          "blueprint_id": "s",
          "deployments": 3
        },
        {
          "blueprint_id": "sg",
          "deployments": 5
        }
      ],
      "deployments": 9,
      "tenant_name": "test2"
    },
    {
      "by blueprint_id": [
        {
          "blueprint_id": "sga",
          "deployments": 3
        },
        {
          "blueprint_id": "s",
          "deployments": 5
        },
        {
          "blueprint_id": "sg",
          "deployments": 1
        }
      ],
      "deployments": 9,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 9
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/deployments?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of deployments based on the target field and optional sub-field.

Response

Field Type Description
items list A list of deployment summaries based on the target field and optional sub-field.

Summarize Executions

Valid fields: status, blueprint_id, deployment_id, workflow_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/executions?_target_field=blueprint_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/executions?_target_field=tenant_name&_sub_field=workflow_id&_all_tenants=true"
# Using CloudifyClient
summaries = client.summary.executions.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/executions'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprint_id": "sga",
      "executions": 6
    },
    {
      "blueprint_id": "s",
      "executions": 10
    },
    {
      "blueprint_id": "sg",
      "executions": 2
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

With sub-field

{
  "items": [
    {
      "by workflow_id": [
        {
          "executions": 9,
          "workflow_id": "create_deployment_environment"
        },
        {
          "executions": 1,
          "workflow_id": "create_snapshot"
        },
        {
          "executions": 9,
          "workflow_id": "install"
        },
        {
          "executions": 1,
          "workflow_id": "restore_snapshot"
        }
      ],
      "executions": 20,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 4
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/executions?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of executions based on the target field and optional sub-field.

Response

Field Type Description
items list A list of execution summaries based on the target field and optional sub-field.

Summarize Node Instances

Valid fields: deployment_id, node_id, host_id, state, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/node_instances?_target_field=deployment_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/node_instances?_target_field=node_id&_sub_field=state"
# Using CloudifyClient
summaries = client.summary.node_instances.get(_target_field='deployment_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/node_instances'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'deployment_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "deployment_id": "s",
      "node_instances": 2
    },
    {
      "deployment_id": "s2",
      "node_instances": 2
    },
    {
      "deployment_id": "s3",
      "node_instances": 2
    },
    {
      "deployment_id": "s4",
      "node_instances": 2
    },
    {
      "deployment_id": "s5",
      "node_instances": 2
    },
    {
      "deployment_id": "sga",
      "node_instances": 51
    },
    {
      "deployment_id": "sga2",
      "node_instances": 51
    }
  ],
  "metadata": {
    "pagination": {
      "total": 7,
      "offset": 0,
      "size": 1000
    }
  }
}

With sub-field

{
  "items": [
    {
      "by state": [
        {
          "node_instances": 42,
          "state": "started"
        }
      ],
      "node_id": "fakeapp1",
      "node_instances": 42
    },
    {
      "by state": [
        {
          "node_instances": 84,
          "state": "started"
        }
      ],
      "node_id": "fakevm2",
      "node_instances": 84
    },
    {
      "by state": [
        {
          "node_instances": 3,
          "state": "started"
        }
      ],
      "node_id": "fakeplatformthing1",
      "node_instances": 3
    },
    {
      "by state": [
        {
          "node_instances": 66,
          "state": "started"
        }
      ],
      "node_id": "fakevm",
      "node_instances": 66
    },
    {
      "by state": [
        {
          "node_instances": 3,
          "state": "started"
        }
      ],
      "node_id": "fakeappconfig1",
      "node_instances": 3
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 5
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/node_instances?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of node instances based on the target field and optional sub-field.

Response

Field Type Description
items list A list of node instance summaries based on the target field and optional sub-field.

Summarize Nodes

Valid fields: deployment_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/nodes?_target_field=deployment_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/nodes?_target_field=tenant_name&_sub_field=deployment_id&_all_tenants=true"
# Using CloudifyClient
summaries = client.summary.nodes.get(_target_field='deployment_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/nodes'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'deployment_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {"deployment_id": "s", "nodes": 1},
    {"deployment_id": "s2", "nodes": 1},
    {"deployment_id": "s3", "nodes": 1},
    {"deployment_id": "s4", "nodes": 1},
    {"deployment_id": "s5", "nodes": 1},
    {"deployment_id": "sga", "nodes": 5},
    {"deployment_id": "sga2", "nodes": 5}
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 7
    }
  }
}

With sub-field

{
    "items": [
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg2",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg3",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga2",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga3",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga4",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga5",
                    "nodes": 5
                }
            ],
            "nodes": 32,
            "tenant_name": "test1"
        },
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "s2",
                    "nodes": 1
                },
                {
                    "deployment_id": "s3",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg2",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg3",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg4",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg5",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                }
            ],
            "nodes": 18,
            "tenant_name": "test2"
        },
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "s2",
                    "nodes": 1
                },
                {
                    "deployment_id": "s3",
                    "nodes": 1
                },
                {
                    "deployment_id": "s4",
                    "nodes": 1
                },
                {
                    "deployment_id": "s5",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga2",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga3",
                    "nodes": 5
                }
            ],
            "nodes": 22,
            "tenant_name": "default_tenant"
        }
    ],
    "metadata": {
        "pagination": {
            "offset": 0,
            "size": 1000,
            "total": 27
        }
    }
}

GET "{manager-ip}/api/v3.1/summary/nodes?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of nodes based on the target field and optional sub-field.

Response

Field Type Description
items list A list of node summaries based on the target field and optional sub-field.

Tasks graphs

The TasksGraph Resource

# Include this code when using the Cloudify Python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>')

Represents a stored tasks graph, created as part of an execution.

Attributes:

Attribute Type Description
id string Unique identifier of this tasks graph
execution_id string ID of the execution that created this tasks graph
name string A label for this tasks graph, so that multiple graphs for a single execution can be distinguished

List tasks graphs

Request Example

$ curl -u user:password "http://<manager-ip>/api/v3.1/tasks_graphs?execution_id=123&name=abc"
client.tasks_graphs.list(execution_id, name)

Response Example

{
    "id": "aaabbbccc",
    "execution_id": "123",
    "name": "abc"
}

GET "{manager-ip}/api/v3.1/tasks_graphs"

Lists tasks graphs. This is useful when filtering by execution ID.

Query Parameters

Property Type Description
execution_id string Filter tasks graphs for this execution
name string Filter tasks graphs with this name

Create tasks graph

Request Example

$ curl -u user:password -X POST \
    -d '{"name": "abc", "execution_id": "123"}' \
    "http://<manager-ip>/api/v3.1/tasks_graphs"
client.tasks_graphs.create(execution_id, name, operations=operations)

Response Example

{
    "id": "aaabbbccc",
    "execution_id": "123",
    "name": "abc"
}

POST "{manager-ip}/api/v3.1/tasks_graphs"

Creates a tasks graph. This can optionally also create a tasks graph with operations in it, where operations is a list of dicts containing a representation of each operation, as returned by its dump method. Operations can also be created one-by-one, however this method should be used instead for performance improvement.

Request Body

Property Type Description
execution_id string ID of the current execution
name string An additional label for the tasks graph to distinguish multiple graphs for the same execution
operations list Serialized operations to create in this tasks graph

Tenants

The Tenant Resource

The Tenant resource is a logical component that represents a closed environment with its own resources.

Attributes:

Attribute Type Description
id integer Auto increment, unique identifier for the tenant.
name string The tenant’s name.

List Tenants

Request Example - Get user and user group counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
  "items": [
    {
      "name": "default_tenant",
      "groups": 0,
      "users": 1
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

Request Example - Get user and user group details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group details

{
  "items": [
    {
      "name": "default_tenant",
      "groups": {},
      "users": {
        "admin": {
          "tenant-role": "user",
          "roles": [
            "user"
          ]
        }
      }
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager_ip}/api/v3.1/tenants"

List all tenants.

Response

Field Type Description
items list A list of Tenant resources.

Get Tenant

Request Example - Get user and user group counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/{tenant_name}"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.get('<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<tenant_name>",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/{tenant_name}?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.get('<tenant_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "admin": {
      "tenant-role": "user",
      "roles": [
        "user"
      ]
    }
  }
}

GET "{manager_ip}/api/v3.1/tenants?name={tenant_name}"

Retrieves a specific tenant.

URI Parameters

Response

A Tenant resource.

Create Tenant

Request Example - Get user and user group counts

$ curl -X POST \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.create('<new_tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<new_tenant_name>",
    "groups": 0,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X POST \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.create('<new_tenant_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group details

{
    "name": "<new_tenant_name>",
    "groups": {},
    "users": {}
}

POST "{manager_ip}/api/v3.1/tenants/{new_tenant_name}"

Creates a tenant.

URI Parameters

Response

A Tenant resource.

Delete Tenant

Request Example - Get user and user group counts

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<tenant_name_to_delete>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.delete('<tenant_name_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name-to-delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name_to_delete",
    "groups": 0,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<tenant_name_to_delete>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.delete('<tenant_name_to_delete>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name_to_delete>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group details

{
    "name": "tenant_name_to_delete",
    "groups": {},
    "users": {}
}

DELETE "{manager_ip}/api/v3.1/tenants/{tenant_name_to_delete}"

Delete a tenant.

URI Parameters

Response

A Tenant resource.

Add User to Tenant

Request Example - Get user and user group counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_add>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user(
    '<username_to_add>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_add>',
    'role': '<role_name>',
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<tenant_name>",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "tenant_name": <tenant_name>, "role": <role_name>}' \
    "http://<manager_ip>/api/v3.1/tenants/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user(
    '<username_to_add>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_add>',
    'role': '<role_name>',
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
    _get_data=True,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "<username_to_add>": {
      "tenant-role": "<role_name>",
      "roles": [
        "<role_name>"
      ]
    }
  }
}

PUT "{manager_ip}/api/v3.1/tenants/users"

Add a user to a tenant.

Request Body

Property Type Description
username string The user name to add to the tenant.
tenant_name string The name of the tenant to which to add the user.
role string The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

Response

A Tenant resource.

Update User in Tenant

Request Example - Get user and user group counts

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_update>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user(
    '<username_to_update>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_update>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_update>, "tenant_name": <tenant_name>, "role": <role_name>}' \
     "http://<manager_ip>/api/v3.1/tenants/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user(
    '<username_to_update>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_update>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "my-user": {
      "tenant-role": "<role_name>",
      "roles": [
        "<role_name>"
      ]
    }
  }
}

PATCH "{manager_ip}/api/v3.1/tenants/users"

Update a user in a tenant.

Request Body

Property Type Description
username string The user name to remove from the tenant.
tenant_name string The tenant name to add the user into it.
role string The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

Response

A Tenant resource.

Remove User from Tenant

Request Example - Get user and user group counts

$ curl -X DELETE \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_remove>", "tenant_name": "<tenant_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user('<username_to_remove>', '<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_remove>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 0,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X DELETE \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_remove>", "tenant_name": "<tenant_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user(
    '<username_to_remove>',
    '<tenant_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_remove>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
    "name": "<tenant_name>",
    "groups": {},
    "users": {}
}

DELETE "{manager_ip}/api/v3.1/tenants/users"

Delete a user from a tenant.

Request Body

Property Type Description
username string The user name to remove from the tenant.
tenant_name string The tenant name to add the user into it.

Response

A Tenant resource.

Add User-Group to Tenant

Request Example - Get user and user group counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 1,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {
    "<group_name>": "<role_name>"
  },
  "users": {}
}

PUT "{manager_ip}/api/v3.1/tenants/user-groups"

Add a user group to a tenant.

Request Body

Property Type Description
group_name string The name of the user group to add to the tenant.
tenant_name string The name of the tenant to which to add the user group.
role string The name of the role assigned to the users members of the group. If not passed the default tenant role will be used.

Valid tenant roles are:

Response

A Tenant resource.

Update User-Group in Tenant

Request Example - Get user and user group counts

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"tenant_name": "<tenant_name>", "group_name": "<group_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/user-groups"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 1,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"tenant_name": "<tenant_name>", "group_name": "<group_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {
    "<group_name>": "<role_name>"
  },
  "users": {}
}

PATCH "{manager_ip}/api/v3.1/tenants/user-groups"

Update a user group in a tenant.

Request Body

Property Type Description
group_name string The group name to update in the tenant.
tenant_name string The tenant name to which the user group is assigned.
role string The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

Response

A Tenant resource.

Remove User-Group from Tenant

Request Example - Get user and user group counts

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user_group('<group_name>', '<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 0,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user_group(
    '<group_name>',
    '<tenant_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
    "name": "tenant_name",
    "groups": {},
    "users": {}
}

DELETE "{manager_ip}/api/v3.1/tenants/user-groups"

Delete a user group from a tenant.

Request Body

Property Type Description
group_name string The name of the user group to delete from the tenant.
tenant_name string The name of the tenant from which to delete the user group.

Response

A Tenant resource.

Tokens

The Tokens Resource

Attributes:

Attribute Type Description
role string The role associated with the token (admin or user)
value string The value of the token

Get Token

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/tokens"
# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3.1/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "role": "admin",
  "value": "WyIwIiwiZjRmNTUzMWRmYmFmZGZmNTlkNTkyZGY2MjMxYzkyNTEiXQ.C_YU9Q.IhQMlnXZIaCtWUUHH_CzHP4-Bg4"
}

GET "{manager-ip}/api/v3.1/tokens"

Gets a token.

Response

A Token resource.

User Groups

The User Group Resource

The User Group is a group of users.

Attributes:

Attribute Type Description
id integer Auto increment, unique identifier for the tenant.
ldap_dn string The distinguished name of corresponding LDAP group (if using LDAP).
name string The name of the user group.

List User Groups

Request Example - Get tenants and users counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<password> \
    "http://<manager_ip>/api/v3.1/user-groups"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users counts

{
  "items": [
    {
      "ldap_dn": "ldap_group_dn",
      "tenants": 0,
      "name": "group_name",
      "users": 0
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

Request Example - Get tenants and users details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<password> \
    "http://<manager_ip>/api/v3.1/user-groups?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users details

{
  "items": [
    {
      "ldap_dn": "ldap_group_dn",
      "tenants": {},
      "name": "group_name",
      "users": []
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager_ip}/api/v3.1/user-groups"

List all user groups.

Response

Field Type Description
items list A list of Group resources.

Get User Group

Request Example - Get tenants and users counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<group_name>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.get('<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<group_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "ldap_group_dn",
  "tenants": 0,
  "name": "<group_name>",
  "users": 0
}

Request Example - Get tenants and users details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<group_name>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.get('<group_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<group_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "ldap_group_dn",
  "tenants": {},
  "name": "<group_name>",
  "users": []
}

GET "{manager_ip}/api/v3.1/user-groups/{group_name}"

Retrieves a specific group.

URI Parameters

Response

A Group resource.

Create User Group

Request Example - Get tenants and users counts

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": <group_name>, "ldap_group_dn": <ldap_group_dn>}' \
    "http://<manager_ip>/api/v3.1/user-groups"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.create(
    group_name='<group_name>',
    ldap_group_dn='<ldap_group_dn>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'group_name': '<group_name>',
    'ldap_group_dn': '<ldap_group_dn>',
}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "<ldap_group_dn>",
  "tenants": 0,
  "name": "<group_name>",
  "users": 0
}

Request Example - Get tenants and users details

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": <group_name>, "ldap_group_dn": <ldap_group_dn>}' \
    "http://<manager_ip>/api/v3.1/user-groups?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.create(
    group_name='<group_name>',
    ldap_group_dn='<ldap_group_dn>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'group_name': '<group_name>',
    'ldap_group_dn': '<ldap_group_dn>',
}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "<ldap_group_dn>",
  "tenants": {},
  "name": "<group_name>",
  "users": []
}

POST -d '{"group_name": <group-name>, "ldap_group_dn": <ldap_group_dn>, "role": <group-system-role>}' "{manager-ip}/api/v3.1/user-groups"

Creates a new user group.

Request Body

Property Type Description
group_name string The group name.
ldap_group_dn string Optional parameter, The distinguishing name of the corresponding LDAP group, if appropriate.
role string Optional parameter, The name of the system role for the group’s users (default: “default”).

Response

A Group resource.

Delete User Group

Request Example - Get tenants and users counts

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.delete('<user_group_name_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users counts

{
    "ldap_dn": "ldap_group_dn",
    "name": "<user_group_name_to_delete>",
    "tenants": 0,
    "users": 0
}

Request Example - Get tenants and users details

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.delete('<user_group_name_to_delete>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users details

{
    "ldap_dn": "ldap_group_dn",
    "name": "<user_group_name_to_delete>",
    "tenants": {},
    "users": []
}

DELETE "{manager_ip}/api/v3.1/user-groups/{user_group_name_to_delete}"

Deletes a user group.

URI Parameters

Response

A Group resource.

Add User to User Group

Request Example - Get tenants and users counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.add_user('<username_to_add>', '<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_add>'
    'group_name': '<group_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "ldap_group_dn",
  "tenants": 0,
  "name": "<group_name>",
  "users": 1
}

Request Example - Get tenants and users details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.add_user(
    '<username_to_add>',
    '<group_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_add>'
    'group_name': '<group_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "ldap_group_dn",
  "tenants": {},
  "name": "<group_name>",
  "users": [
    "<username_to_add>"
  ]
}

PUT "{manager_ip}/api/v3.1/user-groups/users"

Add a user to user group.

Request Body

Property Type Description
username string The name of the user to add to the group.
group_name string The name of the group to which to add the user.

Response

A Group resource.

Remove User from User Group

Request Example - Get tenants and users counts

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_remove>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.remove_user('<username_to_remove>', '<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_remove>'
    'group_name': '<group_name>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "ldap_group_dn",
  "tenants": 0,
  "name": "<group_name>",
  "users": 0
}

Request Example - Get tenants and users details

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_remove>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.remove_user(
    '<username_to_remove>',
    '<group_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_remove>'
    'group_name': '<group_name>',
}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "ldap_group_dn",
  "tenants": {},
  "name": "<group_name>",
  "users": []
}

DELETE "{manager-ip}/api/v3.1/user-groups/users"

Delete a user from a user group.

Request Body

Property Type Description
username string The name of the user to remove from the group.
group_name string The name of the group from which to remove the user.

Response

A Group resource.

Users

The User Resource

Since Cloudify 4.0, Cloudify user management has been added

Attributes:

Attribute Type Description
active boolean Whether the user’s status is active or suspended.
created_at UTCDateTime Date on which the user was created.
first_name string The user’s first name..
id integer Auto increment, unique identifier for the tenant.
last_login_at UTCDateTime Date of last request performed by the user.
last_name string The user’s last name.
password string The user hashed password.
username string The username.

List Users

Request Example - Get tenants and user groups count

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups count

{
  "items": [
    {
      "username": "admin",
      "last_login_at": "2017-10-30T15:45:25.703Z",
      "role": "sys_admin",
      "groups": 0,
      "active": true,
      "tenants": 1
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

Request Example - Get tenants and user groups details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups details

{
  "items": [
    {
      "username": "admin",
      "last_login_at": "2017-10-31T10:38:53.227Z",
      "role": "sys_admin",
      "groups": [],
      "active": true,
      "tenants": {
        "default_tenant": {
          "tenant-role": "user",
          "roles": [
            "user"
          ]
        }
      }
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager_ip}/api/v3.1/users"

List all users.

Response

Field Type Description
items list A list of User resources.

Get User

Request Example - Get tenants and user groups count

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.get(<username>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups count

{
  "username": "admin",
  "last_login_at": "2017-10-30T15:53:04.951Z",
  "role": "sys_admin",
  "groups": 0,
  "active": true,
  "tenants": 1
}

Request Example - Get tenants and user groups details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.get('<username>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups details

{
  "username": "admin",
  "last_login_at": "2017-10-31T10:47:20.220Z",
  "role": "sys_admin",
  "groups": [],
  "active": true,
  "tenants": {
    "default_tenant": {
      "tenant-role": "user",
      "roles": [
        "user"
      ]
    }
  }
}

GET "{manager_ip}/api/v3.1/users/{username}"

Retrieves a specific user.

URI Parameters

Response

A User resource.

Create User

Request Example - Get tenants and user groups count

$ curl -X PUT \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <new_username>, "password": <password>, "role": <role_name>}'
    "http://{manager_ip}/api/v3.1/users"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.create(
    '<new_username>',
    '<password>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<new_username>',
    'password': '<password>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups count

{
  "username": "<new_username>",
  "last_login_at": null,
  "role": "<role_name>",
  "groups": 0,
  "active": true,
  "tenants": 0
}

Request Example - Get tenants and user groups details

$ curl -X PUT \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <new_username>, "password": <password>, "role": <role_name>}'
    "http://{manager_ip}/api/v3.1/users?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.create(
    '<new_username>',
    '<password>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<new_username>',
    'password': '<password>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups details

{
  "username": "<new_username>",
  "last_login_at": null,
  "role": "<role_name>",
  "groups": [],
  "active": true,
  "tenants": {}
}

PUT -d '{"username": <new_username>, "password": <password>, "role": <role_name>}' "{manager_ip}/api/v3.1/users"

Creates a new user.

Request Body

Property Type Description
username string The username.
password string The user password.
role string The user role. One of the following: sys_admin, default.

Valid system roles are:

Response

A User resource.

Delete User

Request Example - Get tenants and user groups count

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username_to_delete>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.delete('<username_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username_to_delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups count

{
  "username": "<username_to_delete>",
  "last_login_at": null,
  "role": "default",
  "groups": 0,
  "active": true,
  "tenants": 0
}

Request Example - Get tenants and user groups details

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username_to_delete>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.delete('<username_to_delete>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username_to_delete>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.delete(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups details

{
  "username": "<username_to_delete>",
  "last_login_at": null,
  "role": "default",
  "groups": [],
  "active": true,
  "tenants": {}
}

DELETE "{manager_ip}/api/v3.1/tenants/{username_to_delete}"

Delete a user.

URI Parameters

Response

A User resource.

Set user password

Request Example - Get tenants and user groups count

$ curl -X POST \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"password": <new_password>}' \
    "http://<manager_ip>/api/v3.1/users/<username>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_password('<username>', '<new_password>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'password': '<new_password>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups count

{
  "username": "<username>",
  "last_login_at": null,
  "role": "default",
  "groups": 0,
  "active": true,
  "tenants": 0
}

Request Example - Get tenants and user groups details

$ curl -X POST \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"password": <new_password>}' \
    "http://<manager_ip>/api/v3.1/users/<username>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_password(
    '<username>',
    '<new_password>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'password': '<new_password>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups details

{
  "username": "<username>",
  "last_login_at": null,
  "role": "default",
  "groups": [],
  "active": true,
  "tenants": {}
}

POST -d '{"password": <new_password>}' '"{manager_ip}/api/v3.1/users/{username}"

Specify a password.

URI Parameters

Request Body

Property Type Description
password string The new user password.

Response

A User resource.

Set user role

Request Example - Get tenants and user groups count

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"role": <user_role>}' \
    "http://<manager_ip>/api/v3.1/users/<username>"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_role('<username>', '<new_role_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'role': '<new_role_name>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups count

{
  "username": "<username>",
  "last_login_at": null,
  "role": "default",
  "groups": 0,
  "active": true,
  "tenants": 0
}

Request Example - Get tenants and user groups details

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"role": <user_role>}' \
    "http://<manager_ip>/api/v3.1/users/<username>?_get_data=true"
# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_role(
    '<username>',
    '<new_role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'role': '<new_role_name>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and user groups details

{
  "username": "<username>",
  "last_login_at": null,
  "role": "default",
  "groups": [],
  "active": true,
  "tenants": {}
}

POST -d '{"role": <new_role_name>}' '"{manager_ip}/api/v3.1/users/{username}"

Set a new system role for the user.

URI Parameters

Request Body

Property Type Description
role string The user role. One of the following: sys_admin, default.

Valid system roles are:

Response

A User resource.