Download OpenAPI specification:Download
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.
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 |
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 |
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.
Data used to log User
email required | string <email> Email address |
password required | string <password> User password |
User profile and JWT
The email/password combination is incorrect.
User is not enabled.
Cannot log in user.
List all ready Recipes available for the authenticated User. This endpoint returns 3 lists of Recipes:
List of Recipes
Cannot list recipes.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/recipes
This endpoint creates a new recipe from the input parameters.
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 |
The created recipe.
Wrong parameters.
Not authorized.
Not allowed.
Service Failed.
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 |
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. |
Recipe is successfully removed.
Wrong parameters.
Not authorized.
The user is not allowed to delete this recipe.
Recipe not found.
Service Failed.
List all Recipes available for the authenticated User.
This endpoint returns a paginated list of all Recipes.
source | string Default: "all" Enum:"all" "official" "owner" "sharee" "shared" Filter by Recipe source. Options are:
|
status | string Default: "all" Enum:"all" "ready" "updating" Filter by Recipe status. Options are:
|
type | string Default: "system" Enum:"system" "app" "all" Filter by Recipe type. Options are:
|
Paginated list of Recipes
Cannot list recipes.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v2/recipes
List all is official Recipes and Recipes of the current user.
source | string Default: "all" Enum:"all" "official" "shared" Filter by Recipe source. Options are:
|
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 |
A list containing all official and related to the user recipes.
Not authorized.
Service Failed.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v3/recipes/
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.
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 |
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 |
stop_when_inactive | boolean Default: false DEPRECATED. Use |
automatic_release | object DEPRECATED. Use |
timeouts | object Various customizable timeouts for the Instance. |
The creating Instance
An instance with the same name already exist for user.
Not allowed to start an instance.
The given recipe cannot be found, or no slots are available on the platform.
Cannot start disposable instance.
List all currently available Instances for the authenticated User. This endpoint is deprecated. /v2/instances should be used instead.
format | string Enum:"template" "recipe" Deprecated. |
List of Instances
Cannot list instances.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/instances
Retrieve an Instance identified by its Uuid.
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 |
format | string Default: "recipe" Enum:"recipe" "template" Deprecated. |
The Instance
Instance does not exit.
Cannot get instance information.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/instances/<UUID>
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.
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 |
The stopping Instance
Instance does not exit.
Cannot stop disposable instance.
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
[STATEFULL] Export running instance data to make it persist over stop
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 instance |
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. |
The instance has successfully been saved.
The user is not allowed to save an instance.
Instance not found.
Service Failed.
List all currently available Instances for the authenticated User.
The following sortable fields are available:
This endpoint is paginated.
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 |
List of Instances
Not allowed to list organization's instances
Cannot list instances.
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'
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 hardware profile to retrieve |
The requested hardware profile.
The user is not allowed to request this hardware profile.
Hardware Profile not found.
Service Failed.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/hardware-profiles/<UUID>
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 hardware profile to retrieve |
Hardware Profile is successfully removed.
Not authorized.
The user is not allowed to delete this hardware profile.
Hardware Profile not found.
Service Failed.
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>
List all is official Hardware Profiles and Hardware Profiles of the current user.
source | string Default: "all" Enum:"all" "official" "owner" Filter by Hardware Profile source. Options are:
|
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 |
A list containing all official and related to the user hardware profiles.
Not authorized.
Service Failed.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/hardware-profiles/
This endpoint creates a new hardware profile from the input parameters.
display_settings required | object (PublicDisplaySettingsPayload) |
parent_hardware_profile_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 Hardware Profile name |
form_factor | string (PublicFormFactor) Enum:"PHONE" "TABLET" Hardware Profile form factor |
release_date | string Nullable ^(\d{4})-(\d){2}-(\d{2})$ Date |
The created hardware profile.
Wrong parameters.
Not authorized.
Not allowed.
Service Failed.
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 OS Image to retrieve |
The requested OS Image.
The user is not allowed to request this OS Image.
OS Image not found.
Service Failed.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/os-images/<UUID>
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 OS Image to retrieve |
OS Image is successfully removed.
Wrong parameters.
Not authorized.
The user is not allowed to delete this Os Image.
OS Image not found.
Service Failed.
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>
List all is official OS Images and OS Images of the current user.
source | string Default: "all" Enum:"all" "official" "owner" Filter by OS Image source. Options are:
|
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 |
A list containing all official and related to the user os images.
Not authorized.
Service Failed.
curl -H 'Content-Type: application/json;charset=utf-8' -H 'x-api-token: <token>' https://api.geny.io/cloud/v1/os-images/
This endpoint duplicates an OS Image from the input 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 OS Image to retrieve |
name required | string OS Image name |
The duplicated OS Image.
Wrong parameters.
Not authorized.
Not allowed.
Service Failed.