How to Bytemark

Show documention menu

Cloud servers

The Cloud Servers API was originally a standalone product called ‘BigV’ — you might find many references to this in the code.

The API is RESTful and so the HTTP method you use determines the type of action you’re performing:

  • GET – Reads existing data.
  • POST – Creates some new data.
  • PUT – Updates some existing data.
  • DELETE – Deletes some data.

It’s also worth noting that our implementation of PUT works like the (newer) PATCH method; it will only update the attributes supplied.


The endpoint (URL) for our Cloud Servers is currently: and all URLs in this section are relative to that URL.

Data format

The API uses the JSON data format. All requests should set Accept and Content-Type headers appropriately. If Content-Type is set incorrectly, POST and PUT will not work.

POST{account-id}/groups HTTP/1.1
Content-type: application/json
Accept: application/json

Nested URLs

Older style endpoints have nested parameters in URLs. Newer style endpoints do not require this nesting and take additional parameters in the query string:

  • account_id
  • account_name
  • group_id
  • group_name
  • vm_id
  • vm_name
  • user_id
  • user_name
  • privilege_id

Newer style endpoints are only available for GET requests. Non-nested POST/PUT/DELETE endpoints are in development.

# Old style
GET /accounts/{account-id}/groups/{group-id}
GET /accounts/{account-id}/groups/{group-id}/virtual_machines
GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/discs

# New style
GET /groups/{group-id}
GET /virtual_machines?group_id={group-id}
GET /discs?vm_id={vm-id}

HTTP Status Codes

Sometimes you will have privileges to use GET on a resource, but will get a 403 if you try to PUT/POST/DELETE to it without having appropriate permissions. If you do not have privileges to GET on the resource, then GET/PUT/POST/DELETE will all return HTTP response code: 404 Not Found.

Requests for unknown resources return HTTP response code: 404 Not Found.

Unexpected errors or server-side problems will return HTTP response code: 500.

The body content for PUT and POST requests is a JSON hash of attribute => value (e.g., {"username":"something"}) for the attributes you would like to update. Unknown attributes are silently discarded. Bad values for known attributes will cause the request to fail with HTTP response code: 400. In this case, the response body will be a JSON hash of attr => [error1, …].

Successful POST requests return HTTP response code: 201 (200 for PUT) and the response body will be a JSON hash describing the newly created (or updated) resource.

Successful GET requests return HTTP 200 and the response body is a JSON hash or array of hashes describing the resource, or resources, requested.

Successful DELETE requests return HTTP 204 (No Content). If a delete fails, a 400 response with a text/plain or application/json body (whichever is most appropriate) will be returned with the reason.

Bytemark Cloud used to be called "BigV"—nothing has changed except the name! We’re hiring! Please visit to find out more.