NAV
curl

Introduction

Welcome to the {panel_name} API reference.

You can use our API to access {panel_name} REST API endpoints with simple HTTP requests to access and manage your cloud infrastructure.

Our platform is API-driven - any functionality that’s available in the UI is also available via the API. Our reference currently covers curl. Bindings for other languages like Ruby and Python are planned.

If you have any questions about the API, you may contact us any time.

Authentication

To access any API end-point, you need to authenticate:

# With shell, you can just pass the correct header with each request
curl "api-endpoint-here"
  -u "api-key-here"

{panel_name} uses API keys to allow access to the API. You can obtain your API key in the panel.

{panel_name} expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: api-key-here

Machines

List All Machines

curl "{panel_url}/api/machines"
  -u "api-key-here"

JSON response:

{
    "machines": [{
        "id": 236,
        "plan": {
            "id": 22,
            "name": null,
            "params": {
                "cpu": 1,
                "memory": 0.5,
                "storage": 21474836480,
                "storage_type": "HDD"
            },
            "period": "monthly",
            "price": {
                "value": 1000,
                "value_without_tax": 1000,
                "tax_value": 0
            },
            "yearly_price": null,
            "hidden": false,
            "archived": false
        },
        "region": {
            "id": 8,
            "name": "America 1",
            "location": "US",
            "hypervisor_count": 1,
            "machines_count": 5
        },
        "status": "stopped",
        "hostname": "my-blog",
        "deleted": false,
        "progress": {
            "create_machine": "Finishing",
            "progress_percent": 25,
            "machine_id": 236
        },
        "progress_id": null,
        "user": {
            "id": 27,
            "email": "test@gmail.com",
            "created_at": "2016-05-19T04:13:30.958Z",
            "updated_at": "2016-06-09T06:18:19.452Z",
            "role": "false",
            "is_admin": false,
            "is_user": true,
            "is_locked": false,
            "panel_owner": false,
            "country": null,
            "state": null,
            "language": null,
            "api_key": "dTf_ASoOEs09ibKxVITdr9XYPBnTr56zm_5nt4X2b0c",
            "api_enabled": true
        },
        "memory": 524288,
        "cpus": 1,
        "storage": [{
            "device": "vda",
            "capacity": 22020096,
            "allocation": 14016
        }],
        "image": {
            "id": 10032,
            "image_type": "template",
            "version": "2016.03.01",
            "progress": null,
            "status": "available",
            "available": true,
            "is_default": false,
            "virtio": true,
            "distribution": {
                "id": 3,
                "name": "Arch",
                "logo_image": null,
                "images": [{
                    "id": 10025,
                    "image_type": "iso",
                    "version": "2016.03.01",
                    "status": "available",
                    "available": true,
                    "is_default": false,
                    "virtio": true,
                    "checksum": "992f046c3fb5afecaf8734126f2a095f437ca9b8",
                    "mirrors": ["Shipped from Virtkick CDN", "http://archmirror.pacmanvps.com/iso/latest/archlinux-2016.03.01-dual.iso"],
                    "template_url": null,
                    "machines_count": 1
                }, {
                    "id": 10032,
                    "image_type": "template",
                    "version": "2016.03.01",
                    "status": "available",
                    "available": true,
                    "is_default": false,
                    "virtio": true,
                    "checksum": "51d9375002f76c4e25d6ee60663796a094b42b4e4be2cd744388fdbbf260f7c30034a67430d2411be38311444222a191a1502c2f9d7074543312fd15ddfee70c",
                    "mirrors": ["Shipped from Virtkick CDN", "Shipped from Virtkick CDN"],
                    "template_url": null,
                    "machines_count": 4
                }]
            }
        },
        "locked": false,
        "ips": [{
            "address": "192.168.92.11",
            "network": "192.168.92.0/24",
            "gateway": "192.168.92.1",
            "netmask": "255.255.255.0/24"
        }],
        "vnc_password": "abcd",
        "cpu_usage": 0,
        "iso_checksum": null,
        "root_password": "seiv7uoW",
        "monthly_paid": 1000,
        "total_paid": 1000
    }]
}

This endpoint retrieves all machines.

Root password to the machine is provided until it’s dismissed, afterwards it’s set to null.

HTTP Request

GET {panel_url}/api/machines

Query Parameters

Parameter Default Description
include_image false If set to true, the result will also include image and template details.

Retrieve Machine

curl "{panel_url}/api/machines/2"
  -u "api-key-here"

Response:

{
  "id": 236,
  "plan": {
    "id": 22,
    "name": null,
    "params": {
      "cpu": 1,
      "memory": 0.5,
      "storage": 21474836480,
      "storage_type": "HDD"
    },
    "period": "monthly",
    "price": {
      "value": 1000,
      "value_without_tax": 1000,
      "tax_value": 0
    },
    "yearly_price": null,
    "hidden": false,
    "archived": false
  },
  "region": {
    "id": 8,
    "name": "America 1",
    "location": "US",
    "hypervisor_count": 1,
    "machines_count": 5
  },
  "status": "stopped",
  "hostname": "my-blog",
  "deleted": false,
  "progress": {
    "create_machine": "Finishing",
    "progress_percent": 25,
    "machine_id": 236
  },
  "progress_id": null,
  "user": {
    "id": 27,
    "email": "test@gmail.com",
    "created_at": "2016-05-19T04:13:30.958Z",
    "updated_at": "2016-06-09T06:18:19.452Z",
    "role": "false",
    "is_admin": false,
    "is_user": true,
    "is_locked": false,
    "panel_owner": false,
    "country": null,
    "state": null,
    "language": null,
    "api_key": "dTf_ASoOEs09ibKxVITdr9XYPBnTr56zm_5nt4X2b0c",
    "api_enabled": true
  },
  "memory": 524288,
  "cpus": 1,
  "storage": [{
    "device": "vda",
    "capacity": 22020096,
    "allocation": 14016
  }],
  "image": {
    "id": 10032,
    "image_type": "template",
    "version": "2016.03.01",
    "progress": null,
    "status": "available",
    "available": true,
    "is_default": false,
    "virtio": true,
    "distribution": {
      "id": 3,
      "name": "Arch",
      "logo_image": null,
      "images": [{
        "id": 10025,
        "image_type": "iso",
        "version": "2016.03.01",
        "status": "available",
        "available": true,
        "is_default": false,
        "virtio": true,
        "checksum": "992f046c3fb5afecaf8734126f2a095f437ca9b8",
        "mirrors": ["Shipped from Virtkick CDN", "http://archmirror.pacmanvps.com/iso/latest/archlinux-2016.03.01-dual.iso"],
        "template_url": null,
        "machines_count": 1
      }, {
        "id": 10032,
        "image_type": "template",
        "version": "2016.03.01",
        "status": "available",
        "available": true,
        "is_default": false,
        "virtio": true,
        "checksum": "51d9375002f76c4e25d6ee60663796a094b42b4e4be2cd744388fdbbf260f7c30034a67430d2411be38311444222a191a1502c2f9d7074543312fd15ddfee70c",
        "mirrors": ["Shipped from Virtkick CDN", "Shipped from Virtkick CDN"],
        "template_url": null,
        "machines_count": 4
      }]
    }
  },
  "locked": false,
  "ips": [{
    "address": "192.168.92.11",
    "network": "192.168.92.0/24",
    "gateway": "192.168.92.1",
    "netmask": "255.255.255.0/24"
  }],
  "vnc_password": "abcd",
  "cpu_usage": 0,
  "iso_checksum": null,
  "root_password": "seiv7uoW",
  "monthly_paid": 1000,
  "total_paid": 1000
}

This endpoint retrieves a specific machine.

HTTP Request

GET {panel_url}/api/machines/<id>

URL Parameters

Parameter Description
include_image false

Delete Machine

curl "{panel_url}/api/machines/<id>"
  -X DELETE
  -u "api-key-here"

JSON response:

{
  "progress_id": "23155cd2938c629dbee87f79",
  "data": null
}

This endpoint deletes a specific machine.

HTTP Request

DELETE {panel_url}/api/machines/<id>

Errors

The {panel_name} API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed.
401 Unauthorized – Your API key is wrong.
403 Forbidden – The resource requested is hidden for administrators only.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
406 Not Acceptable – You requested a format that isn’t JSON.
429 Too Many Requests – You’ve hit the limits. Please contact us to have your limits increased.
500 Internal Server Error – We had a problem with our server. That’s probably a bug - please let us know.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.
curl