logo
API docs by Redocly

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.

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
required

Data used to log User

email
required
string <email> (Email)

Email address

password
required
string <password>

User password

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "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

Request samples 

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

Response samples

Content type
application/json
{
  • "base": [
    ],
  • "user": [
    ],
  • "shared": [
    ]
}

Create a new recipe

This endpoint creates a new recipe from the input parameters.

Authorizations:
ApiTokenBearer
Request Body schema: application/json
required
hardware_profile_uuid
required
string <uuid> (Uuidv4) ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][...

Resource unique identifier

os_image_uuid
required
string <uuid> (Uuidv4) ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][...

Resource unique identifier

parent_recipe_uuid
string or null <uuid> (NullableUuidv4) ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][...

Resource unique identifier

name
required
string or null

Recipe name

description
string

Recipe description

Responses

Request samples

Content type
application/json
{
  • "hardware_profile_uuid": "45d3646a-9489-4a40-aa87-addaa499c31b",
  • "os_image_uuid": "d46548f5-0f78-43d8-b745-5f67ed0c7915",
  • "parent_recipe_uuid": "7f02aa13-3f42-4289-88bd-199e2080217c",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "parent_recipe_uuid": "7f02aa13-3f42-4289-88bd-199e2080217c",
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "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][...

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

Request samples

Content type
application/json
{
  • "delete_hardware_profile": false,
  • "delete_os_image": false
}

Response samples

Content type
application/json
{
  • "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

Request samples 

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

Response samples

Content type
application/json
{
  • "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
arch
Array of strings
Default: "x86_64,x86"
Items Enum: "x86" "x86_64" "arm64"

Filter by the architecture of the related image.

If this isn't specified, x86 and x86_64 will be used by default.

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

Request samples 

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

Response samples

Content type
application/json
{
  • "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][...

Uuid of the resource

Request Body schema: application/json
required

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.

object

DEPRECATED. Use timeouts instead.

object

Various customizable timeouts for the Instance.

Responses

Request samples

Content type
application/json
{
  • "instance_name": "string",
  • "rename_on_conflict": false,
  • "stop_when_inactive": false,
  • "automatic_release": {
    },
  • "timeouts": { }
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "owner_uuid": "a528e82a-c54a-4046-8831-44d7f9028f54",
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "hardware_profile": {
    },
  • "os_image": {
    },
  • "state": "CREATING",
  • "streamer_fqdn": "string",
  • "turn_fqdn": "string",
  • "adb_url": "string",
  • "file_upload_url": "string",
  • "webrtc_url": "string",
  • "recipe_uuid": "597eb633-0943-4de5-b80a-1b0319522204",
  • "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"

Deprecated.

Responses

Request samples 

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

Response samples

Content type
application/json
[
  • {
    }
]

Get a token to connect to an instance.

Returns a token to be used for connecting to an instance.

Authorizations:
ApiTokenBearer
Request Body schema: application/json
instance_uuid
string <uuid>

Instance uuid.

This is required to connect to instances with arm64 architecture.

Responses

Request samples

Content type
application/json
{
  • "instance_uuid": "7e61f2db-030b-4d58-8326-9509e91716e2"
}

Response samples

Content type
application/json
{
  • "access_token": "string"
}

Get Instance

Retrieve an Instance 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][...

Uuid of the resource

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

Deprecated.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "owner_uuid": "a528e82a-c54a-4046-8831-44d7f9028f54",
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "hardware_profile": {
    },
  • "os_image": {
    },
  • "state": "CREATING",
  • "streamer_fqdn": "string",
  • "turn_fqdn": "string",
  • "adb_url": "string",
  • "file_upload_url": "string",
  • "webrtc_url": "string",
  • "recipe_uuid": "597eb633-0943-4de5-b80a-1b0319522204",
  • "created_at": "string",
  • "updated_at": "string",
  • "timeout": 0,
  • "timeouts": {
    },
  • "recipe": {
    },
  • "owner": {
    }
}

Stop disposable Instance

Stop the given disposable Instance identified by its Uuid.

The Instance will automatically be destroyed right after it has been stopped.

The state of the Instance returned by this call will always be STOPPING, unless it was already in SAVING or DELETING state. In this case, the call will succeed but the instance will continue its end-of-life cycle.

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

Uuid of the resource

Responses

Request samples 

curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' --data '{}' https://api.geny.io/cloud/v1/instances/<UUID>/stop-disposable

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "owner_uuid": "a528e82a-c54a-4046-8831-44d7f9028f54",
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "hardware_profile": {
    },
  • "os_image": {
    },
  • "state": "CREATING",
  • "streamer_fqdn": "string",
  • "turn_fqdn": "string",
  • "adb_url": "string",
  • "file_upload_url": "string",
  • "webrtc_url": "string",
  • "recipe_uuid": "597eb633-0943-4de5-b80a-1b0319522204",
  • "created_at": "string",
  • "updated_at": "string",
  • "timeout": 0,
  • "timeouts": {
    },
  • "recipe": {
    },
  • "owner": {
    }
}

Save a running instance in order to reuse it later

[STATEFULL] Export running instance data to make it persist over stop

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

UUID of the instance

Request Body schema: application/json
action
string
Default: "SAVE_AS"
Enum: "SAVE" "SAVE_AS"

Specify if the recipe should be updated in place, or if a new recipe should be created.

SAVE will update the custom recipe. SAVE can only be used if the current user is the owner of the custom recipe. If a the image is official, a new custom image will be created. Otherwise the existing custom image will be updated.

SAVE_AS will create a new custom recipe and a new custom image.

When a new custom recipe is created, it will have the name specified by new_recipe_name. If no new_recipe_name is specified, the new custom recipe will be named "Copy of toriginal recipe name)"

When a new custom image is created, it will have the name specified by new_os_image_name. If no new_os_image_name is specified, the new custom image will be named "Copy of (original image name)"

new_recipe_name
string

Name of the new created recipe. Used in case of action=SAVE_AS.

new_os_image_name
string

Name of the new created OS Image. Used in case of action=SAVE and current OsImage is official, or if action=SAVE_AS.

Responses

Request samples

Content type
application/json
{
  • "action": "SAVE",
  • "new_recipe_name": "string",
  • "new_os_image_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Instances v2

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:
ApiTokenBearer
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][...

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

state
string

Instance state to filter

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Hardware Profile v1

Retrieve Hardware Profile 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][...

Uuid of the hardware profile to retrieve

Responses

Request samples 

curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/hardware-profiles/<UUID>

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "display_settings": {
    },
  • "parent_hardware_profile_uuid": "c2b24ad9-266c-4839-915f-e2ff070fbe70",
  • "name": "string",
  • "is_official": true,
  • "owner": {
    },
  • "form_factor": "PHONE",
  • "cpu_count": 0,
  • "ram_size": 0,
  • "data_disk_size": 0,
  • "release_date": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "recipe_count": 0
}

Delete Hardware Profile 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][...

Uuid of the hardware profile to retrieve

Responses

Request samples 

curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' -X "DELETE" https://api.geny.io/cloud/v1/hardware-profiles/<UUID>

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

List Hardware Profiles

List all is official Hardware Profiles and Hardware Profiles of the current user.

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

Filter by Hardware Profile source. Options are:

  • official: Hardware Profiles provided by Genymotion, available to everyone
  • owner: Hardware Profiles created by authenticated User
  • all: combination of official & owner
search
string

Search term to search on name attribute.

page
integer

Page to fetch

page_size
integer
Default: 30

Number of hardware profiles per page

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Create a new hardware profile

This endpoint creates a new hardware profile from the input parameters.

Authorizations:
ApiTokenBearer
Request Body schema: application/json
required
required
object (PublicDisplaySettingsPayload)
parent_hardware_profile_uuid
string or null <uuid> (NullableUuidv4) ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][...

Resource unique identifier

name
required
string

Hardware Profile name

form_factor
string (PublicFormFactor)
Enum: "PHONE" "TABLET"

Hardware Profile form factor

release_date
string or null (NullableShortDate) ^(\d{4})-(\d){2}-(\d{2})$

Date

Responses

Request samples

Content type
application/json
{
  • "display_settings": {
    },
  • "parent_hardware_profile_uuid": "c2b24ad9-266c-4839-915f-e2ff070fbe70",
  • "name": "string",
  • "form_factor": "PHONE",
  • "release_date": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "display_settings": {
    },
  • "parent_hardware_profile_uuid": "c2b24ad9-266c-4839-915f-e2ff070fbe70",
  • "name": "string",
  • "is_official": true,
  • "owner": {
    },
  • "form_factor": "PHONE",
  • "cpu_count": 0,
  • "ram_size": 0,
  • "data_disk_size": 0,
  • "release_date": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "recipe_count": 0
}

OS Image v1

Retrieve OS Image 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][...

Uuid of the OS Image to retrieve

Responses

Request samples 

curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/os-images/<UUID>

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "os_version": {
    },
  • "parent_os_image_uuid": "cbcb716b-9ff1-4221-877f-79705bbb170e",
  • "supported_form_factors": [
    ],
  • "name": "string",
  • "is_official": true,
  • "is_beta": true,
  • "arch": "x86",
  • "owner": {
    },
  • "status": "CREATING",
  • "image_version": "string",
  • "image_uri": "string",
  • "image_size_bytes": 0,
  • "image_hash": "string",
  • "image_date": "string",
  • "build_date": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "recipe_count": 0
}

Delete OS Image 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][...

Uuid of the OS Image to retrieve

Responses

Request samples 

curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' -X "DELETE" https://api.geny.io/cloud/v1/os-images/<UUID>

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

List OS Images

List all is official OS Images and OS Images of the current user.

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

Filter by OS Image source. Options are:

  • official: OS Images provided by Genymotion, available to everyone
  • owner: OS Images created by authenticated User
  • all: combination of official & owner
arch
Array of strings
Default: "x86_64,x86"
Items Enum: "x86" "x86_64" "arm64"

Filter by the image architecture.

If this isn't specified, x86 and x86_64 will be used by default.

search
string

Search term to search on name attribute.

page
integer

Page to fetch

page_size
integer
Default: 30

Number of os images per page

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "count": 0,
  • "results": [
    ]
}

Duplicate an OS Image

This endpoint duplicates an OS Image from the input parameters.

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

Uuid of the OS Image to retrieve

Request Body schema: application/json
required
name
required
string

OS Image name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "os_version": {
    },
  • "parent_os_image_uuid": "cbcb716b-9ff1-4221-877f-79705bbb170e",
  • "supported_form_factors": [
    ],
  • "name": "string",
  • "is_official": true,
  • "is_beta": true,
  • "arch": "x86",
  • "owner": {
    },
  • "status": "CREATING",
  • "image_version": "string",
  • "image_uri": "string",
  • "image_size_bytes": 0,
  • "image_hash": "string",
  • "image_date": "string",
  • "build_date": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "recipe_count": 0
}