NAV
shell

CloudAMQP API🔗

Documentation for the CloudAMQP API.

The API is used for creating instances and more and are available to customers that have signed up via https://www.cloudamqp.com.

The Instance API can be used after you have created your instance. Use it to manage alarms, integrations, RabbitMQ, the firewall, VPC peering and more.

Get the API key for the Instance API from the get instance info endpoint.

You can also use Terraform to manage your CloudAMQP resources. See the documentation at the Terraform Registry.

Authentication🔗

Authentication is done by sending your API key in the password field in Basic Auth, the username should be kept empty.

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://customer.cloudamqp.com/api/instances

You can find, or create, your API keys at https://customer.cloudamqp.com/apikeys

Instances🔗

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/instances

The above command returns JSON structured like this:

[
  {
    "id": 1234,
    "plan": "squirrel-1",
    "region": "amazon-web-services::eu-west-1",
    "name": "My test",
    "tags": ["test-instance"],
    "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "vpc_id": 5678
  }
]

This endpoint retrieves all instances.

GET https://customer.cloudamqp.com/api/instances

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/instances/1234

The above command returns JSON structured like this:

{
  "id": 1234,
  "plan": "squirrel-1",
  "region": "amazon-web-services::eu-west-1",
  "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "My test",
  "tags": ["test-instance"],
  "url": "amqp://user:password@fluffy-unicorn.rmq2.cloudamqp.com/vhost",
  "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
  "ready": true,
  "rmq_version": "3.9.9",
  "urls": {
    "external": "amqps://user:password@fluffy-unicorn.rmq2.cloudamqp.com/vhost",
    "internal": "amqp://user:password@fluffy-unicorn.in.rmq2.cloudamqp.com/vhost"
  },
  "hostname_external": "fluffy-unicorn.rmq2.cloudamqp.com",
  "hostname_internal": "fluffy-unicorn.in.rmq2.cloudamqp.com"
}

This endpoint retrieves a specific instance.

The API key returned in this response is the key that you will use for the Instance API that we have. That API is per instance and there you can configure alarms, log and metric integrations and more.

That documentation for the Instance API can be found here: Instance API Documentation

GET https://customer.cloudamqp.com/api/instances/<ID>

Parameter Description
ID The ID of the instance to retrieve
  curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "name=test&plan=tiger&region=amazon-web-services::us-east-1&tags=test-instance" \
  https://customer.cloudamqp.com/api/instances

The above command returns JSON structured like this:

{
  "id": 2234,
  "url": "amqp://user:password@lemur.cloudamqp.com/vhost",
  "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
}

This endpoint creates an instance. Name, plan and region are required.

POST https://customer.cloudamqp.com/api/instances

Parameter Description
name The name of the instance
plan Which subscription plan and node combination to use, e.g. lemur, bunny-3, rabbit-5.
region Name of the region you want to create your instance in
tags Tags for instance (array or comma separated list)
vpc_subnet Dedicated VPC subnet, shouldn't overlap with your current VPC's subnet.
vpc_id Id of an existing VPC to add the new instance to.
nodes Number of nodes in cluster, plan must support it. (Deprecated)
rmq_version RabbitMQ version
copy_settings If you want to copy settings from an existing subscription.

When using copy_settings, the body must be sent as JSON. Below is an example that will copy alarms, metrics, logs, firewall and config from subscription with id: 2234

{
    "name": "My new instance",
    "plan": "bunny-1",
    "region": "amazon-web-services::us-east-1",
    "copy_settings": {
        "subscription_id": 2234,
        "settings": ["alarms", "metrics", "logs", "firewall", "config"],
    }
}

Available settings to copy are alarms, definitions, metrics, logs, firewall, plugins, config

subscription_id is a required parameter, it indicates what instance to copy the settings from.

settingsis a required parameter that contains a list of settings to copy.

More information about copy_settings feature

  curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d"name=test2&plan=lemur&tags=test-instance,dev-team" \
  https://customer.cloudamqp.com/api/instances/1234

This endpoint updates an instance

PUT https://customer.cloudamqp.com/api/instances/<ID>

Parameter Description
ID The ID of the instance to update
Parameter Description
name The name of the instance
plan Which subscription plan and node combination to use, e.g. lemur, bunny-3, rabbit-5.
tags Tags for instance (array or comma separated list)
nodes Number of nodes in cluster, plan must support it. (Deprecated)
  curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "extra_disk_size=100" \
  https://customer.cloudamqp.com/api/instances/1234/disk
  curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "extra_disk_size=100&allow_downtime=true" \
  https://customer.cloudamqp.com/api/instances/1234/disk

This endpoint can be used to resize the disk size of an instance. Default behaviour is to expand the disk without any downtime. Currently limited to instances in Amazon Web Services (AWS) and Google Compute Engine (GCE).

Using the optional request parameter allow_downtime=true to allow cluster downtime if necessary when resizing disk. This will affect resize action taken such as swap the disk, override time rate limit or shrink the disk. Currently limited to instances in Amazon Web Services (AWS), Google Compute Engine (GCE) as optional and required for Azure.

PUT https://customer.cloudamqp.com/api/instances/<ID>/disk

Parameter Description
ID The ID of the instance to update
Parameter Description
extra_disk_size Disk size to add, in gigabytes. Supported values: 0, 25, 50, 100, 250, 500, 1000, 2000
allow_downtime (Optional) Allow cluster downtime if needed when resizing disk. Action taken such as swap the disk, override time rate limit or shrink the disk.
  curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/instances/1234

This endpoint deletes an instance

DELETE https://customer.cloudamqp.com/api/instances/<ID>

Parameter Description
ID The ID of the instance to delete

VPCs🔗

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/vpcs

The above command returns JSON structured like this:

[
  {
    "id": 5678,
    "plan": "vpc",
    "region": "amazon-web-services::eu-west-1",
    "name": "My test",
    "tags": ["test-instance"],
    "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subnet": "10.56.72.0/24",
    "instances": [1234]
  }
]

This endpoint retrieves all VPCs.

GET https://customer.cloudamqp.com/api/vpcs

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/vpcs/5678

The above command returns JSON structured like this:

{
  "id": 5678,
  "plan": "vpc",
  "region": "amazon-web-services::eu-west-1",
  "name": "My test",
  "tags": ["test-instance"],
  "providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subnet": "10.56.72.0/24",
  "instances": [1234]
}

This endpoint retrieves a specific VPC.

GET https://customer.cloudamqp.com/api/vpcs/<ID>

Parameter Description
ID The ID of the instance to retrieve
  curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d "name=test&&region=amazon-web-services::us-east-1&tags=test-vpc&subnet=10.56.72.0/24" \
  https://customer.cloudamqp.com/api/vpcs

The above command returns JSON structured like this:

{
  "id": 2234,
  "apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
}

This endpoint creates a VPC. Name, subnet and region are required.

POST https://customer.cloudamqp.com/api/vpcs

Parameter Description
name The name of the VPC
region Name of the region you want to create your VPC in
tags Tags for VPC (array or comma separated list)
subnet Dedicated VPC subnet, shouldn't overlap with your current VPC's subnet.
  curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d"name=test2tags=test-instance,dev-team" \
  https://customer.cloudamqp.com/api/vpcs/5678

This endpoint update an instance

PUT https://customer.cloudamqp.com/api/vpcs/<ID>

Parameter Description
ID The ID of the vpcs to update
Parameter Description
name The name of the VPC
tags Tags for VPC (array or comma separated list)
  curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/vpcs/5678

This endpoint deletes a VPC

DELETE https://customer.cloudamqp.com/api/vpcs/<ID>

Parameter Description
ID The ID of the VPC to delete

Invoices🔗

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/invoices

The above command returns JSON structured like this:

[
  {
    "id": 1234,
    "period": "2022/5",
    "number": 2345,
    "paid": false,
    "total": 929,
    "currency": "USD",
    "account_name": "84codes AB"
  },
  {
    "id": 6789,
    "period": "2022/6",
    "number": 7890,
    "paid": true,
    "total": 99,
    "currency": "USD",
    "account_name": "84codes AB"
  },
  ...
]

GET https://customer.cloudamqp.com/api/invoices

Parameter Description
from Year-month start, e.g. 2022-05
to Year-month end, e.g. 2022-06
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/invoices/period

The above command returns JSON structured like this:

{
  "period": "2022/6",
  "total": 16.1,
  "currency": "USD",
  "lines": [
    {
      "subscription_id": 187,
      "amount": 16.1,
      "from": "2022-06-01T00:00:00+00:00",
      "to": "2022-06-10T15:51:29+00:00",
      "name": "Test server",
      "plan": "squirrel-1",
      "tags": []
    }
  ],
  "customer": {
    "company": "Cool company",
    "address": "The park",
    "country": "Sweden",
    "account_name": "Cool company"
  },
  "seller": {
    "company": "84codes AB",
    "address": "C/O United Spaces Torsgatan 26",
    "zipcode": "113 21 Stockholm",
    "country": "Sweden",
    "vatid": "SE556898078201"
  }
}

GET https://customer.cloudamqp.com/api/invoices/period

Parameter Description
year Year to calculate for
month Year-month end, e.g. 2022-06
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/invoices/<id>

The above command returns JSON structured like this:

{
  "period": "2022/6",
  "total": 16.1,
  "currency": "USD",
  "lines": [
    {
      "subscription_id": 187,
      "amount": 16.1,
      "from": "2022-06-01T00:00:00+00:00",
      "to": "2022-06-10T15:51:29+00:00",
      "name": "Test server",
      "plan": "squirrel-1",
      "tags": []
    }
  ],
  "customer": {
    "company": "Cool company",
    "address": "The park",
    "country": "Sweden",
    "account_name": "Cool company"
  },
  "seller": {
    "company": "84codes AB",
    "address": "C/O United Spaces Torsgatan 26",
    "zipcode": "113 21 Stockholm",
    "country": "Sweden",
    "vatid": "SE556898078201"
  }
}

GET https://customer.cloudamqp.com/api/invoices/<id>

Parameter Description
id The invoice id

Auditlog🔗

Returns auditlog in CSV format for latest month, or for month specified in params.

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/auditlog/csv

The above command text formatted in a CSV on following format:

Timestamp,Event,Source,User,Extras
2022-12-12 11:05:17 UTC,login,web,john@company.com,type = pwd
2022-12-12 09:52:16 UTC,login,web,jane@company.com,type = pwd

GET https://customer.cloudamqp.com/api/auditlog/csv

Parameter Description
timestamp YYYY-MM , e.g. 2022-12

Regions🔗

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/regions

The above command returns JSON structured like this:

[
  {
    "provider": "amazon-web-services",
    "region": "us-east-1",
    "name": "Amazon Web Services - US-East-1 (Northern Virginia)",
    "has_shared_plans": true
  },
  {
    "provider": "google-compute-engine",
    "region": "us-central1",
    "name": "Google Compute Engine - us-central1 (Iowa)",
    "has_shared_plans": true
  },
  ...
]
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/regions?provider=amazon-web-services

The above command returns JSON structured like this:

[
  {
    "provider": "amazon-web-services",
    "region": "us-east-1",
    "name": "Amazon Web Services - US-East-1 (Northern Virginia)",
    "has_shared_plans": true
  },
  ...
]

GET https://customer.cloudamqp.com/api/regions

Parameter Description
provider Filter result with a specific provider, e.g. amazon-web-services.

Team🔗

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/team

The above command returns JSON structured like this:

[
  {
    "id": "f49afe6f-7b96-496e-8966-72daddfb897b",
    "email": "john@company.com",
    "tfa_auth_enabled": false,
    "roles": [
      "member"
    ]
  },
  {
    "id": "823e6c7d-2a94-4cc7-9615-4d699ebea95c",
    "email": "jane@company.com",
    "tfa_auth_enabled": true,
    "roles": [
      "admin"
    ]
  }
]

GET https://customer.cloudamqp.com/api/team

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx -d \
"email=john@company.com" https://customer.cloudamqp.com/api/team/invite

The command below is for a user with specific role

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx -d \
"email=jane@company.com&role=member&tags=tag1,tag2" https://customer.cloudamqp.com/api/team/invite

All the above commands returns JSON structured like this:

{"message":"Email invitation sent"}

This endpoint invites a user to team POST https://customer.cloudamqp.com/api/team/invite

The user will get the role member by default if no role is specified.

Parameter Description
email The user's email
role User's role in the team
tags Tag roles for member and monitor users
Roles Permissions
admin Full access to team and instances
devops Full access to instances (including create/delete)
member Manage Instances (access control panel)
monitor View Instances (restricted access control panel)
Not allowed to reconfigure, restart, reboot etc.
billing manager Full Billing access
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
-d "email=jane@company.com" https://customer.cloudamqp.com/api/team/remove

The above command returns JSON structured like this:

{"message":"The user has been deleted from team"}

This endpoint removes a user from team POST https://customer.cloudamqp.com/api/team/remove

Parameter Description
email The user's email
curl -X PUT -u xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx: \  
-d "tags=tag1,tag2,tag3&role=member" https://customer.cloudamqp.com/api/team/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

The above command returns JSON structured like this:

{"message":"Role and tags updated for user."}

This endpoint updates role and tags for a user in a team PUT https://customer.cloudamqp.com/api/team/{user-id}

This endpoint requires at least one of the following optional parameters to be provided:

Parameter Required Type Description
role false string User's role in the team
tags false string List of user's tags in the team (separated by comma; "tag1,tag2,tag3")
Roles Permissions
admin Full access to team and instances
billing manager Full Billing access
devops Full access to instances (including create/delete)
member Manage Instances (access control panel)
monitor View Instances (restricted access control panel)
Not allowed to reconfigure, restart, reboot etc.

API keys🔗

The API key used in the request will be removed. A new API key with matching permissions will be created and returned in the response. The comment of the old key will be carried over to the new key.

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/apikeys/rotate-apikey

The above command returns JSON structured like this:

{
  "apikey": "..."
}

POST https://customer.cloudamqp.com/api/apikeys/rotate-apikey

Plans🔗

All prices are in USD and per month. Read more on which plans are available at https://www.cloudamqp.com/plans.html

curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/plans

The above command returns JSON structured like this:

[
  {
    "name": "plan-a",
    "price": 0,
    "backend": "some-service",
    "shared": true
  },
  {
    "name": "plan-b",
    "price": 99,
    "backend": "another-service",
    "shared": false
  }
  ...
]
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  https://customer.cloudamqp.com/api/plans?backend=some-service

The above command returns JSON structured like this:

[
  {
    "name": "plan-a",
    "price": 0,
    "backend": "some-service",
    "shared": true
  },
  ...
]

GET https://customer.cloudamqp.com/api/plans

Parameter Description
backend Filter result with a specific backend software, e.g. some-service.

Formats🔗

All API end points support form FormData and JSON in the request. You need to format the request accordingly and if you send the request as JSON be sure to add the content type header content-type: application/json otherwise the server won't be able to parse your request.

Status Codes🔗

Status Code Meaning
200 The request completed successfully.
204 The request completed successfully.
400 Bad Request -- Your request might be invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
429 Too Many Requests -- Rate limiting, you have requested too many kittens in a given amount of time.
500 Internal Server Error -- We had a problem with our server. Try again later.