Getting Started

The VMPower API is a mostly REST-style, mostly JSON API compliant Web API. This API is the same one that powers the VMPower Dashboard.

Usage of the VMPower public API is currently under private beta. Contact support@vmpower.io in order to request access.

Getting Your API Key and Secret

You'll need an API Key and API Secret to authenticate to the VMPower API.

To create a key:

Your API key never changes but you can generate a secret at any time. For your security, we can only show the secret to you once. Store this secret and do not expose it publicly as it allows access to your VMPower subscription.

Base URL

All API paths are based off of the official VMPower API url:

https://api.vmpower/io

Authentication and Required Headers

To authenticate to the VMPower API you'll need to set 3 headers in every request:

  • Content-Type: application/vnd.api+json
  • x-api-key: YOUR API KEY
  • x-api-secret: YOUR API SECRET

Using the API

JSON API Documents

Most VMPower APIs are JSON API compliant. Generally speaking, every request and response body has a top-level data field with a data.id inner field which is the resource identifier. The inner field data.type represents the resource type (such as users, vm-schedules, etc.). Attributes can be found under the data.attributes field.

Relationships are links from one resource type to another. For example a User resource may have multiple Cloud Subscription resources. These cloud subscriptions can be found under data.relationships.cloud-subscriptions.

All fields are always lowercase and dasherized.

Here's an example JSON API document for a VMPower user by calling the path:

GET https://api.vmpower.io/users/[:user_id]

{
            "id": "59c42a981cf693e367024af2",
            "type": "users",
            "attributes": {
                "first-name": "Steve",
                "last-name": "Edouard",
                "email": "steve@vmpower.io",
                "notification-email": null,
                "notification-email-confirmed": false,
                "account-type": null,
                "slack-auth-code": "",
                "slack-token": "",
                "slack-channel": "",
                "card-last4": null,
                "card-zip": null,
                "card-month": null,
                "card-year": null,
                "card-brand": null,
                "card-id": "",
                "billing-name": "",
                "trialing": true,
                "trial-used": true,
                "organization": "VMPower Inc",
                "team-member-cap": 0,
                "team-cap": 0,
                "stripe-token": "",
                "stripe-id": "",
                "slack-notifications": true,
                "stripe-sub-id": "",
                "price-cap": 1000,
                "scale-number": "1",
                "vm-cap": 3,
                "plan-percentage": 0,
                "plan": 0.5,
                "monthly-savings": 0,
                "email-notifications": true,
                "last-invoice-month": null,
                "created-at": "2017-09-21T21:09:43.815Z",
                "last-detection-time": "2017-09-21T21:06:45.292Z",
                "detection-frequency-days": 1,
                "plan-expiring": true,
                "plan-expire-time": "2017-10-05T21:11:33.707Z",
                "email-confirmed": true,
                "auto-enable-vms": true,
                "aws-customer-id": null,
                "enable-two-factor": false,
                "aws-marketplace-token": null,
                "monthly-volume-cost": 0,
                "monthly-vm-cost": 0,
                "source": "",
                "send-invoices": false,
                "beta-user": false,
                "api-secret-hash": null
            },
            "links": {
                "self": "http://127.0.0.1:3000/users/59c42a981cf693e367024af2"
            },
            "relationships": {
                "team": {
                    "data": null,
                    "links": {
                        "self": "http://127.0.0.1:3000/users/59c42a981cf693e367024af2/relationships/team"
                    }
                },
                "teams-owned": {
                    "data": [],
                    "links": {
                        "self": "http://127.0.0.1:3000/users/59c42a981cf693e367024af2/relationships/teams-owned"
                    }
                },
                "vm-groups": {
                    "data": [
                        {
                            "type": "vm-groups",
                            "id": "59c42b561cf693e367024b02"
                        }
                    ],
                    "links": {
                        "self": "http://127.0.0.1:3000/users/59c42a981cf693e367024af2/relationships/vm-groups"
                    }
                },
                "cloud-subscriptions": {
                    "data": [
                        {
                            "type": "cloud-subscriptions",
                            "id": "59c42b281cf693e367024af8"
                        },
                        {
                            "type": "cloud-subscriptions",
                            "id": "59c42b281cf693e367024af9"
                        },
                        {
                            "type": "cloud-subscriptions",
                            "id": "59c42b281cf693e367024afa"
                        },
                        {
                            "type": "cloud-subscriptions",
                            "id": "59c42b281cf693e367024afb"
                        }
                    ],
                    "links": {
                        "self": "http://127.0.0.1:3000/users/59c42a981cf693e367024af2/relationships/cloud-subscriptions"
                    }
                }
            }
        }

Operations

For most APIs you can delete, update and create resources. Certain APIs may not let you modify specific fields or perform specific actions. Those APIs will respond with a standard response Error.

  • GET - Retrieves the resource(s)
  • PATCH - Modifies the resource, using provided the resource JSON in the request body
  • POST - Creates a new resource of the provided data.id and data.type in the request. Do not provide a data.id field, the server will automatically generate an ID for your new resource.
  • DELETE - Deletes the resource

For POST requests, you do not need to include any metadata fields such as links.

Errors

Errors always take the form of the JSON API compliant error schema. For example here is an error encountered for a rate limit violation:

{
    "errors": [
        {
            "status": "400",
            "code": "Rate Limit Exceeded",
            "title": "You are limited to 75 request per second. Please try again in a few seconds."
        }
    ]
}
  • status - Describes the HTTP response status
  • code - Describes the general error type
  • title - Provides more information about the specific error

Rate Limiting

As of October 2017, VMPower public APIs are subject to a rate limit of up to 75 requests per second.