Skip to main content

File Storage API Endpoints

Use the Storage API methods to upload and manage your app and any file dependencies required for testing.

Refer to Getting Started for Authentication and Server information.

What You'll Need

Get App Storage Files

GET /v1/storage/files

Returns the set of files that have been uploaded to Sauce Storage by the requestor.

Parameters

q

| QUERY | OPTIONAL | STRING |

Any search term (such as app name, file name, description, build number or version) by which you want to filter results.

name

| QUERY | OPTIONAL | STRING |

The file name (case-insensitive) by which you want to search files.

kind

| QUERY | OPTIONAL | ARRAY of STRINGS |

The app type associated with the file, such as android or ios.

file_id

| QUERY | OPTIONAL | ARRAY of STRINGS |

One or more specific IDs of the files to return.

sha256

| QUERY | OPTIONAL | STRING |

SHA-256 hexadecimal (64 chars) hash of the file to look for.

icon_repr

| QUERY | OPTIONAL | STRING |

Available values are:

  • base64
  • hash
. The default value is base64. If set to hash, then only the icon_hash field will be populated in the file metadata, while the icon field will always be null. This helps to reduce the overall size of the JSON response significantly.

tag

| QUERY | OPTIONAL | ARRAY of STRINGS |

One or more tags to only include files having these tags assigned into the resulting JSON. AND condition is applied if more than one tag is provided

team_id

| QUERY | OPTIONAL | ARRAY of STRINGS |

One or more IDs of teams with which the files are shared.

org_id

| QUERY | OPTIONAL | ARRAY of STRINGS |

One or more IDs of organizations with which the files are shared.

page

| QUERY | OPTIONAL | INTEGER |

Return results beginning with a specific page. Default is 1.

per_page

| QUERY | OPTIONAL | STRING |

The number of results (max. 100) to be shown per page.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/files' | json_pp

Responses

200Success.
Sample Response
{
"items": [
{
"id": "eac15989-311a-4dde-9e77-b695323de369",
"owner": {
"id": "13ef3c9f777549aba58c29d9af4dfcbf",
"org_id": "d35a179b33394553ba0e35e0f22aabb3"
},
"name": "iOS-Simulator-MyRNDemoApp.1.3.0-162.zip",
"upload_timestamp": 1652180523,
"etag": "CLTu7Ynk1PcCEAE=",
"kind": "ios",
"group_id": 396353,
"size": 6743553,
"description": null,
"tags": [],
"metadata": {
"identifier": "com.saucelabs.mydemoapp.rn",
"name": "My Demo App",
"version": "162",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "1.3.0",
"is_simulator": true,
"min_os": "12.0",
"target_os": "15.4",
"test_runner_plugin_path": null,
"device_family": [
"phone"
]
},
"access": {
"team_ids": [
"a4cd325b896c4b2db5dc7c853fed31c4"
],
"org_ids": []
},
"sha256": "a3925c6ece9e85695b3fba001560f8f59e4162cb511058c058bcbc2271429a6e"
},
{
"id": "591d8591-f9eb-42b7-903c-bf1ae189a358",
"owner": {
"id": "13ef3c9f777549aba58c29d9af4dfcbf",
"org_id": "d35a179b33394553ba0e35e0f22aabb3"
},
"name": "iOS-Simulator-MyRNDemoApp.1.3.0-162.zip",
"upload_timestamp": 1652180522,
"etag": "CLXq+ojk1PcCEAE=",
"kind": "ios",
"group_id": 396353,
"size": 6743553,
"description": null,
"tags": [],
"metadata": {
"identifier": "com.saucelabs.mydemoapp.rn",
"name": "My Demo App",
"version": "162",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "1.3.0",
"is_simulator": true,
"min_os": "12.0",
"target_os": "15.4",
"test_runner_plugin_path": null,
"device_family": [
"phone"
]
},
"access": {
"team_ids": [
"a4cd325b896c4b2db5dc7c853fed31c4"
],
"org_ids": []
},
"sha256": "a3925c6ece9e85695b3fba001560f8f59e4162cb511058c058bcbc2271429a6e"
},
{
"id": "61c5d1f1-7baa-4e1f-84fd-371da916cd26",
"owner": {
"id": "13ef3c9f777549aba58c29d9af4dfcbf",
"org_id": "d35a179b33394553ba0e35e0f22aabb3"
},
"name": "iOS-Simulator-MyRNDemoApp.1.3.0-162.zip",
"upload_timestamp": 1652180517,
"etag": "CJ7jyYbk1PcCEAE=",
"kind": "ios",
"group_id": 396353,
"size": 6743553,
"description": null,
"tags": [],
"metadata": {
"identifier": "com.saucelabs.mydemoapp.rn",
"name": "My Demo App",
"version": "162",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "1.3.0",
"is_simulator": true,
"min_os": "12.0",
"target_os": "15.4",
"test_runner_plugin_path": null,
"device_family": [
"phone"
]
},
"access": {
"team_ids": [
"a4cd325b896c4b2db5dc7c853fed31c4"
],
"org_ids": []
},
"sha256": "a3925c6ece9e85695b3fba001560f8f59e4162cb511058c058bcbc2271429a6e"
}
],
"links": {
"prev": null,
"next": null,
"self": "?q=162&page=1&per_page=25"
},
"page": 1,
"per_page": 25,
"total_items": 3
}

Get App Storage Groups

GET /v1/storage/groups

Returns an array of groups (apps containing multiple files) currently in storage for the authenticated requestor.

Parameters

q

| QUERY | OPTIONAL | STRING |

Any search term (such as build number or file name) by which you want to filter results.

kind

| QUERY | OPTIONAL | STRING |

The app type associated with the group, such as android or ios.

group_id

| QUERY | OPTIONAL | ARRAY of STRINGS |

One or more specific IDs of the groups to return.

project_name

| QUERY | OPTIONAL | STRING |

The project name of the groups to return. If no project_name is provided, only groups with no projects assigned are provided. You can look up projects by using the GET /v1/storage/projects endpoint.

icon_repr

| QUERY | OPTIONAL | STRING |

Available values are:

  • base64
  • hash
. The default value is base64. If set to hash, then only the icon_hash field will be populated in the file metadata, while the icon field will always be null. This helps to reduce the overall size of the JSON response significantly.

page

| QUERY | OPTIONAL | INTEGER |

Return results beginning with a specific page. Default is 1.

per_page

| QUERY | OPTIONAL | STRING |

The number of results (max. 100) to be shown per page.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/groups' | json_pp

Responses

200Success.
404Not found.
Sample Response
{
"items": [
{
"id": 64612,
"name": "com.saucelabs.SwagLabsMobileApp",
"project_path": "My Swag Project",
"recent": {
"id": "43732d5b-5275-4a79-a936-197e4b9cd2d4",
"owner": {
"id": "e5be7513ba224f6f9463c209cb4c5d83",
"org_id": "bed0a8a559404117b3d10d3bfff4c8ab"
},
"name": "iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa",
"upload_timestamp": 1618522437,
"etag": "184d1c399251e8849edcb0adfc079571",
"kind": "ios",
"group_id": 64612,
"description": null,
"tags": [],
"metadata": {
"identifier": "com.saucelabs.SwagLabsMobileApp",
"name": "SwagLabsMobileApp",
"version": "12",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "2.7.1",
"is_simulator": false,
"min_os": "10.0",
"target_os": "14.2",
"test_runner_plugin_path": null
}
},
"access": {
"team_ids": [
"80d69d16ebdb4c018cc9d81ea911761a"
],
"org_ids": []
},
"count": 1,
"access": {...},
"settings": {
"proxy": {
"host": "",
"port": 0
},
"proxy_enabled": false,
"lang": "en_GB",
"orientation": null,
"resigning_enabled": true,
"resigning": {
"image_injection": true,
"group_directory": false,
"biometrics": true,
"sys_alerts_delay": false
}
}
}
],
"links": {...},
"page": 1,
"per_page": 25,
"total_items": 1
}

Get App Storage Group Settings

GET /v1/storage/groups/{group_id}/settings

Returns the settings of an app group with the given ID.

Parameters

group_id

| PATH | REQUIRED | INTEGER |

The unique identifier of the app group. You can look up group IDs using the Get App Storage Groups endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/groups/2175303/settings' | json_pp

Responses

200Success.
404Not found.
Sample Response
{
"settings": {
"proxy": {
"host": "",
"port": 0
},
"audio_capture": false,
"proxy_enabled": false,
"lang": "en_GB",
"orientation": null,
"resigning_enabled": true,
"resigning": {
"image_injection": true,
"group_directory": false,
"biometrics": false,
"sys_alerts_delay": false,
"network_capture": false
}
},
"kind": "ios",
"identifier": "com.saucelabs.mydemoapp.ios"
}

Edit App Storage Group Settings

PUT /v1/storage/groups/{group_id}/settings

Adds or updates the settings of an app group with the given ID.

Parameters

group_id

| PATH | REQUIRED | INTEGER |

The unique identifier of the app group. You can look up group IDs using the Get App Storage Groups endpoint.

json body

| BODY | REQUIRED | STRING |

The app group's settings. See the sample response below for the available settings.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" \
--request PUT 'https://api.us-west-1.saucelabs.com/v1/storage/groups/2175303/settings' \
--header 'Content-Type: application/json' \
--data-raw '{"settings":{"resigning":{"image_injection":false}}}'\

Responses

201Created.
400The provided group identifier is not a valid one or the provided settings object is invalid.
401Authorization failed.
403The current user does not have enough permissions to change the group.
404The group does not exist or is not accessible.
406The settings cannot be set for the given group type.
Sample Response
{
"settings": {
"proxy": {
"host": "",
"port": 0
},
"audio_capture": false,
"proxy_enabled": false,
"lang": "en_GB",
"orientation": null,
"resigning_enabled": true,
"resigning": {
"image_injection": true,
"group_directory": false,
"biometrics": false,
"sys_alerts_delay": false,
"network_capture": false
}
},
"kind": "ios",
"identifier": "com.saucelabs.mydemoapp.ios"
}

Upload File to App Storage

POST /v1/storage/upload

Uploads an app file to Sauce Storage for the purpose of mobile app testing or generic files to be used as Pre-Run Executables and returns a unique file ID assigned to the uploaded file. Sauce Storage supports mobile app packages in *.apk, *.aab, *.ipa, or *.zip format as well as any other file format. The maximum size of a single file is limited to 4GB.

Parameters

payload

| FORM-FILE | REQUIRED | STRING |

The path to the file you want to upload.

name

| FORM-TEXT | REQUIRED | STRING |

The portion of the payload value that is the actual file name (including the type extension).

description

| FORM-TEXT | OPTIONAL | STRING |

A description to distinguish your app.

tags

| FORM-TEXT | OPTIONAL | STRING |

An optional list of comma-separated tag names assigned to the uploaded file. Each tag name length must be between 1 and 16 characters. Tag names must only consist of uppercase (A-Z), lowercase (a-z), digits (0-9), underscore ("_"), hyphen ("-"), and dot (".") characters. Tag names are case-sensitive. It is allowed to assign up to 10 tags to a single file.

project_name

| FORM-TEXT | OPTIONAL | STRING |

An optional name for the project you want the file (group) to be assigned to. If the project doesn't exist, it will be created. Project names can only consist of alphanumeric (uppercase and lowercase) characters, along with underscores ("_"), hyphens ("-"), periods ("."), and spaces (" "). Project names are case-sensitive and can be max 64 characters long.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request POST 'https://api.us-west-1.saucelabs.com/v1/storage/upload' \
--form 'payload=@"g16K4P8IX/iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa"' \
--form 'name="iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa"' \
--form 'description="iOS Test App v3"'

Responses

201Created.
400Bad Request.
404Not found.
Sample Response
{
"item": {
"id": "7a154f05-835f-469a-93cf-880647d3a8ab",
"owner": {
"id": "******",
"org_id": "******"
},
"name": "iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa",
"upload_timestamp": 1619035533,
"etag": "184d1c399251e8849edcb0adfc079571",
"kind": "ios",
"group_id": 64612,
"description": null,
"tags": [],
"metadata": {
"identifier": "com.saucelabs.SwagLabsMobileApp",
"name": "SwagLabsMobileApp",
"version": "12",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "2.7.1",
"is_simulator": false,
"min_os": "10.0",
"target_os": "14.2",
"test_runner_plugin_path": null
},
"access": {...}
}
}

Download a File from App Storage

GET /v1/storage/download/{file_id}

Returns an app file from Sauce Storage as a payload object in the response.

Parameters

file_id

| PATH | REQUIRED | STRING |

The Sauce Labs identifier of the stored file. You can look up file IDs using the Get App Storage Files endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/download/43732d5b-5275-4a79-a936-197e4b9cd2d4' --output SwagLabsMobileApp.ipa

Responses

200Success.
404Not found.
Sample Response
PK
�����(BwQ��������������Payload/UX ��a�_�a�_��PK
�����*BwQ��������������Payload/SwagLabsMobileApp.app/UX ��a�_�b�_��PK
�����(BwQ������������-��Payload/SwagLabsMobileApp.app/_CodeSignature/UX ��a�_�a�_��PK���*BwQ������������:��Payload/SwagLabsMobileApp.app/_CodeSignature/CodeResourcesUX ��a�_�a�_���}i��H����_QS�3#ؼ$�Zt��x��(R�$�m�oR"���+�]6%R.WX, ��+���$3##"#����,����MT���~���;���߾�5�����/�7J"��LWQ~'�ā#������2���Ҩ���j�=d��}����ö-�'�����֧O}t���@��ҫ������ ����1̏����n�����k�
...

Edit a Stored File

PUT /v1/storage/files/{file_id}

Adds or updates various attributes of the specified file.

Parameters

file_id

| PATH | REQUIRED | STRING |

The Sauce Labs identifier of the stored file. You can look up file IDs using the Get App Storage Files endpoint.

description

| BODY | OPTIONAL | STRING |

A description to more clearly distinguish the stored file in the Sauce Labs system.

tags

| BODY | OPTIONAL | STRING |

An optional list of comma-separated tag names assigned to the uploaded file. Each tag name length must be between 1 and 16 characters. Tag names must only consist of uppercase (A-Z), lowercase (a-z), digits (0-9), underscore ("_"), hyphen ("-"), and dot (".") characters. Tag names are case-sensitive. It is allowed to assign up to 10 tags to a single file. The value overrides the previously set tags.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request PUT 'https://api.us-west-1.saucelabs.com/v1/storage/files/43732d5b-5275-4a79-a936-197e4b9cd2d4' \
--header 'Content-Type: text/html' \
--data-raw '{
"item": {
"description": "Sauce Docs iOS Test App",
"tags": "Europe,Asia,US"
}
}'\

Responses

200Success.
400Bad Request.
404Not found.
Sample Response
{
"item": {
"id": "43732d5b-5275-4a79-a936-197e4b9cd2d4",
"owner": {
"id": "e5be7513ba224f6f9463c209cb4c5d83",
"org_id": "bed0a8a559404117b3d10d3bfff4c8ab"
},
"name": "iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa",
"upload_timestamp": 1618522437,
"etag": "184d1c399251e8849edcb0adfc079571",
"kind": "ios",
"group_id": 64612,
"description": "Sauce Docs iOS Test App",
"tags": ["Europe", "Asia", "US"],
"metadata": {
"identifier": "com.saucelabs.SwagLabsMobileApp",
"name": "SwagLabsMobileApp",
"version": "12",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "2.7.1",
"is_simulator": false,
"min_os": "10.0",
"target_os": "14.2",
"test_runner_plugin_path": null
},
"access": {...}
},
"changed": true
}

Delete an App Storage File

DELETE /v1/storage/files/{file_id}

Deletes the specified file from Sauce Storage.

Parameters

file_id

| PATH | REQUIRED | STRING |

The Sauce Labs identifier of the stored file. You can look up file IDs using the Get App Storage Files endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/v1/storage/files/43732d5b-5275-4a79-a936-197e4b9cd2d4' | json_pp

Responses

200Success.
404Not found.
Sample Response
{
"item": {
"id": "43732d5b-5275-4a79-a936-197e4b9cd2d4",
"owner": {
"id": "e5be7513ba224f6f9463c209cb4c5d83",
"org_id": "bed0a8a559404117b3d10d3bfff4c8ab"
},
"name": "iOS.RealDevice.SauceLabs.Mobile.Sample.app.2.7.1.ipa",
"upload_timestamp": 1618522437,
"etag": "184d1c399251e8849edcb0adfc079571",
"kind": "ios",
"group_id": 64612,
"description": "Sauce Docs iOS Test App",
"tags": [],
"metadata": {
"identifier": "com.saucelabs.SwagLabsMobileApp",
"name": "SwagLabsMobileApp",
"version": "12",
"is_test_runner": false,
"icon": "...",
"icon_hash": "...",
"short_version": "2.7.1",
"is_simulator": false,
"min_os": "10.0",
"target_os": "14.2",
"test_runner_plugin_path": null
},
"access": {...}
}
}

Delete a Group of App Storage Files

DELETE /v1/storage/groups/{group_id}

Deletes the specified group of files from Sauce Storage.

Parameters

group_id

| PATH | REQUIRED | STRING |

The Sauce Labs identifier of the group of files. You can look up file IDs using the Get App Storage Groups endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/v1/storage/groups/64612' | json_pp

Responses

200Success.
Sample Response
{
"code": 404,
"title": "NotFound",
"detail": "The group identified by \"64612\" does not exist or is not accessible (Request ID: nancy.swee__delete_group__35803e43)"
}

Get File Icon

GET /v1/storage/icons/{icon_hash}

Returns the actual payload for the given icon hash. All icons are stored in .png format. This endpoint supports caching.
icon_hash

| PATH | REQUIRED | STRING |

Hash string of the particular icon. You can look up icon hashes using the Get App Storage Files endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/icons/<icon_hash>' --output icon.png

Responses

200Success.
404Not found.

List Tags

GET/v1/storage/tags

Returns the list of tags available for your team sorted alphabetically. Each tag name is only returned if assigned to at least one file.
page

| QUERY | OPTIONAL | INTEGER |

Return results beginning with a specific page. Default is 1.

per_page

| QUERY | OPTIONAL | STRING |

The number of results (max. 100) to be shown per page.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/tags'

Responses

200Success.
Sample Response
{
"items": [
"Asia",
"Europe",
"US"
]
"links": {
"prev": null,
"next": null,
"self": "?page=1&per_page=25"
},
"page": 1,
"per_page": 25,
"total_items": 3
}

List Projects

GET/v1/storage/projects

Returns an alphabetically sorted list of projects available for your team. Each project name is only returned if assigned to at least one file (group).
kind

| QUERY | OPTIONAL | STRING |

The app type associated with the project(s), such as

  • android
  • ,
  • ios
  • or
  • other
.

page

| QUERY | OPTIONAL | INTEGER |

Return results beginning with a specific page. Default is 1.

per_page

| QUERY | OPTIONAL | STRING |

The number of results (max 100) to be shown per page.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v1/storage/projects'

Responses

200Success.
Sample Response
{
"items": [
"Asia",
"Buenos Aires",
"Europe",
"Los Angeles",
"US"
]
"links": {
"prev": null,
"next": null,
"self": "?page=1&per_page=25"
},
"page": 1,
"per_page": 25,
"total_items": 5
}