logo
Documentation Powered by ReDoc

Genymotion SaaS Public HTTP API (2.0.0)

Download OpenAPI specification:Download

Genymotion SaaS Team: [email protected] URL: https://cloud.geny.io/

Genymotion SaaS user documentation can be found at docs.genymotion.com/saas.

This HTTP API allows you to manage Genymotion SaaS virtual devices.

There are 3 main concepts in this API. All of them must be understood in order to able to use the it efficiently.

The first concept is the use of JWT (JSON Web Token) to authenticate the API calls. With the exception of the authentication, all endpoints require the JWT to be passed in the Authorization HTTP header as bearer. If the JWT is missing, invalid or expired, the API call will return a 401 Unauthorized HTTP error.

The second concept is the Recipe. A Recipe is what is needed to cook an Instance. This Recipe contains the information about the Android system, the virtual device characteristics, and some contextual data. Genymobile provides a variety of default Recipes, but you can create and share new ones from either the Genymotion SaaS Portal or from the Genymotion Desktop software (license required).

The third concept is the Instance. An Instance represents a Genymotion Virtual Device running in the Cloud. Built using the information contained in a Recipe, an Instance can be accessed using a wide variety of tools. The current API allows you to start and stop disposable Instances. A disposable Instance will always be recreated from the Recipe when a start request is sent. When a stop request is sent, the virtual device Instance will be destroyed, and any modifications done inside it during the run time will be lost.

Authentication

Bearer

Authorization HTTP header, with Bearer <JWT> content format, for authentication mechanism.

Except for the authentication endpoint, all API calls require this HTTP header to be set in order to identify the user executing the request on the platform.

Not passing it to the API call, or providing an invalid/expired one, will result in a 401 Unauthorized HTTP error.

Security scheme type: API Key
Header parameter name: Authorization

Users

Authenticate User

Authenticate a User, and retreive a new valid JWT. This JWT must be provided to all other API calls in order to identify and authenticate the User executing the request.

Once logged in, simply add the Authorization HTTP header to all subsequents API calls. Authorization HTTP header value must have the following format: Bearer <JWT>.

A JWT will expire after some time. The default validity duration is 48 hours. It is recommended to generate a new one before running a new set of API calls. Generating a new JWT will not invalidate previously generated JWTs.

Request Body schema: application/json

Data used to log User

email
required
string <email>

Email address

password
required
string <password>

User password

Responses

200

User profile and JWT

401

The email/password combination is incorrect.

403

User is not enabled.

default

Cannot log in user.

post /v1/users/login
https://api.geny.io/cloud/v1/users/login

Request samples

application/json
Copy
 Expand all Collapse all
{}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Recipes v1

List Recipes

List all ready Recipes available for the authenticated User. This endpoint returns 3 lists of Recipes:

  • Bases Recipes, the default Recipes, provided by Genymobile and always available to all Users
  • User Recipes, Recipes shared to any other User by the currently authenticated User
  • Shared Recipes, Recipes shared by any other User to the currently authenticated User
Authorizations:
Bearer

Responses

200

List of Recipes

default

Cannot list recipes.

get /v1/recipes
https://api.geny.io/cloud/v1/recipes

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer <JWT>' https://api.geny.io/cloud/v1/recipes

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "base":
    [
    ],
  • "user":
    [
    ],
  • "shared":
    [
    ]
}

Recipes v2

List Recipes (paginated)

List all Recipes available for the authenticated User.

This endpoint returns a paginated list of all Recipes.

Authorizations:
Bearer
query Parameters
source
string
Default: "all"
Enum:"all" "official" "owner" "sharee" "shared"

Filter by Recipe source.

Options are:

  • official: Recipes provided by Genymotion, available to everyone
  • owner: Recipes created by authenticated User
  • sharee: Recipes shared to authenticated User or their Organization
  • shared: combination of owner & sharee
  • all: combination of official & shared
status
string
Default: "all"
Enum:"all" "ready" "updating"

Filter by Recipe status.

Options are:

  • ready: Recipes you can use to start an Instance with
  • updating: Recipes currently being updating (cannot be used to start an Instance yet)
  • all: combination of ready & updating
type
string
Default: "system"
Enum:"system" "app" "all"

Filter by Recipe type.

Options are:

  • system: Recipes based on a full-fledged system
  • app: Recipes based on an Android application (APK)
  • all: combination of system & app

Responses

200

Paginated list of Recipes

default

Cannot list recipes.

get /v2/recipes
https://api.geny.io/cloud/v2/recipes

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer <JWT>' https://api.geny.io/cloud/v2/recipes

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results":
    [
    ]
}

Instances

Start disposable Instance

Start a new disposable Instance from the given Recipe identified by its Uuid.

The Instance is disposable, meaning that all changes done inside it will be lost after the Instance is stopped.

The state of the Instance returned by this call will always be CREATING.

Authorizations:
Bearer
path Parameters
uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Uuid of the resource

Request Body schema: application/json

Data used to start new disposable Instance

instance_name
required
string

Name of the Instance. This name must be unique per User.

rename_on_conflict
boolean
Default: false

In case a virtual device already exist with the same name, allow the Platform to rename the Instance with a new, unique, name. New name will look like instance_name followed by some characters generated by the Platform.

stop_when_inactive
boolean
Default: false

DEPRECATED. Use timeouts.inactivity instead.

automatic_release
object

DEPRECATED. Use timeouts instead.

timeouts
object

Various customizable timeouts for the Instance.

Responses

201

The creating Instance

400

An instance with the same name already exist for user.

403

Not allowed to start an instance.

404

The given recipe cannot be found, or no slots are available on the platform.

default

Cannot start disposable instance.

post /v1/recipes/{uuid}/start-disposable
https://api.geny.io/cloud/v1/recipes/{uuid}/start-disposable

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "instance_name": "string",
  • "rename_on_conflict": false,
  • "stop_when_inactive": false,
  • "automatic_release":
    {
    },
  • "timeouts":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "uuid": "string",
  • "name": "string",
  • "owner_uuid": "string",
  • "organization_uuid": "string",
  • "hardware_profile":
    {
    },
  • "os_image":
    {
    },
  • "state": "CREATING",
  • "streamer_fqdn": "string",
  • "turn_fqdn": "string",
  • "adb_url": "string",
  • "file_upload_url": "string",
  • "webrtc_url": "string",
  • "recipe_uuid": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "timeout": 0,
  • "timeouts":
    {
    },
  • "recipe":
    {
    },
  • "owner":
    {
    }
}

List Instances (deprecated) Deprecated

List all currently available Instances for the authenticated User. This endpoint is deprecated. /v2/instances should be used instead.

Authorizations:
Bearer
query Parameters
format
string
Enum:"template" "recipe"

Deprecated.

Responses

200

List of Instances

default

Cannot list instances.

get /v1/instances
https://api.geny.io/cloud/v1/instances

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer <JWT>' https://api.geny.io/cloud/v1/instances

Response samples

application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

List Instances

List all currently available Instances for the authenticated User.

The following sortable fields are available:

  • name (Instance name)
  • created_at (Instance creation datetime)
  • updated_at (Instance update datetime)
  • owner (Uuid of the Instance owner)
  • state (Instance state)

This endpoint is paginated.

Authorizations:
Bearer
query Parameters
ordering
string^[\+|\-]?[,1-9a-zA-Z_\-]*$

Use an orderable field with an optional '+' OR '-' prefix to order in the desired direction

page
integer

Page to query

page_size
integer

Number of elements per pages

organization_uuid
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Uuid of the organization. Only an organization manager can use this filter.

state
string

Instance state to filter

Responses

200

List of Instances

403

Not allowed to list organization's instances

default

Cannot list instances.

get /v2/instances
https://api.geny.io/cloud/v2/instances

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer <JWT>' 'https://api.geny.io/cloud/v2/instances?state=BOOTING&state=ONLINE&ordering=created_at'

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results":
    [
    ]
}

Get Instance

Retrieve an Instance identified by its Uuid.

Authorizations:
Bearer
path Parameters
uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Uuid of the resource

query Parameters
format
string
Default: "recipe"
Enum:"recipe" "template"

Deprecated.

Responses

200

The Instance

404

Instance does not exit.

default

Cannot get instance information.

get /v1/instances/{uuid}
https://api.geny.io/cloud/v1/instances/{uuid}

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer <JWT>' https://api.geny.io/cloud/v1/instances/<UUID>

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "uuid": "string",
  • "name": "string",
  • "owner_uuid": "string",
  • "organization_uuid": "string",
  • "hardware_profile":
    {
    },
  • "os_image":
    {
    },
  • "state": "CREATING",
  • "streamer_fqdn": "string",
  • "turn_fqdn": "string",
  • "adb_url": "string",
  • "file_upload_url": "string",
  • "webrtc_url": "string",
  • "recipe_uuid": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "timeout": 0,
  • "timeouts":
    {
    },
  • "recipe":
    {