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 Authentication. An API token or JWT (JSON Web Token) must be used to authenticate the API calls. The authentication endpoint itself does not accept an API token or JWT. In the Genymotion SaaS Public HTTP API, all endpoints other than the authentication endpoint accept either API token or JWT authentication.

For endpoints requiring authentication, exactly one of the API token or the JWT must be provided. If neither are provided, the API call will return a 401 Unauthorized HTTP error. If both are provided, the API call will return a 400 Bad Request HTTP error.

The details of each authentication scheme are provided below, in Authentication.

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

ApiToken

x-api-token HTTP header, with the api-token as the value.

API tokens may be created in the Genymotion SaaS Portal.

Providing an invalid API token will result in a 401 Unauthorized HTTP error.

Providing an API token on an endpoint which does not support API token authentication will result in a 403 Forbidden HTTP error.

Providing both an API token and a JWT Authorization will result in a 400 Bad Request HTTP error.

Security scheme type: API Key
Header parameter name: x-api-token

Bearer

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

Use the Authenticate User endpoint to obtain a JWT.

Providing an invalid/expired JWT will result in a 401 Unauthorized HTTP error.

Providing both a JWT Authorization and an API token will result in a 400 Bad Request HTTP error.

Security scheme type: API Key
Header parameter name: Authorization

Users v1

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:
ApiTokenBearer

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 'x-api-token: <token>' https://api.geny.io/cloud/v1/recipes

Response samples

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

Create a new recipe

This endpoint creates a new recipe from the input parameters.

Authorizations:
ApiTokenBearer
Request Body schema: application/json
hardware_profile_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}$

Resource unique identifier

os_image_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}$

Resource unique identifier

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

Resource unique identifier

name
required
string Nullable

Recipe name

description
string

Recipe description

Responses

201

The created recipe.

400

Wrong parameters.

401

Not authorized.

403

Not allowed.

500

Service Failed.

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

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "hardware_profile_uuid": "string",
  • "os_image_uuid": "string",
  • "parent_recipe_uuid": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "parent_recipe_uuid": "string",
  • "uuid": "string",
  • "hardware_profile":
    {
    },
  • "os_image":
    {
    },
  • "name": "string",
  • "is_official": true,
  • "owner":
    {
    },
  • "description": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "status": "CREATING"
}

Delete Recipe identified by its uuid

Authorizations:
ApiTokenBearer
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 recipe to retrieve

Request Body schema: application/json
delete_hardware_profile
boolean
Default: false

Define if we delete the recipe hardware profile.

delete_os_image
boolean
Default: false

Define if we delete the recipe OS image.

Responses

204

Recipe is successfully removed.

400

Wrong parameters.

401

Not authorized.

403

The user is not allowed to delete this recipe.

404

Recipe not found.

500

Service Failed.

delete /v1/recipes/{uuid}
https://api.geny.io/cloud/v1/recipes/{uuid}

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "delete_hardware_profile": false,
  • "delete_os_image": false
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "code": "string",
  • "message": "string"
}

Recipes v2

List Recipes (paginated)

List all Recipes available for the authenticated User.

This endpoint returns a paginated list of all Recipes.

Authorizations:
ApiTokenBearer
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 'x-api-token: <token>' https://api.geny.io/cloud/v2/recipes

Response samples

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

Recipes v3

List Recipes

List all is official Recipes and Recipes of the current user.

Authorizations:
ApiTokenBearer
query Parameters
source
string
Default: "all"
Enum:"all" "official" "shared"

Filter by Recipe source. Options are:

  • official: Recipes provided by Genymotion, available to everyone
  • shared: combination of recipes :
    • created by the authenticated User
    • shared to authenticated User or their Organization
  • all: combination of official & shared
search
string

Search term to search on name or uuid attributes.

page
integer

Page to fetch

page_size
integer
Default: 30

Number of recipes per page

Responses

200

A list containing all official and related to the user recipes.

401

Not authorized.

500

Service Failed.

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

Request samples

Copy
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v3/recipes/

Response samples

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

Instances v1

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:
ApiTokenBearer
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:
ApiTokenBearer
query Parameters
format
string
Enum:"template" "recipe"