Option One:

Sauce REST uses HTTP Basic Authentication base64 encoded Username and API Access Key. Send the 'Authorization: Basic ...' header to authenticate your requests.

Example:

$ curl --basic -u 'demo-user:access-key' https://saucelabs.com/rest/v1/demo-user/jobs

Option Two:

Alternatively, you can place the user name and password directly in the URLs.

Example:

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs

Login a subaccount to saucelabs.com and retrieve login cookies:

$ curl -D - -X POST https://demo-user:access-key@saucelabs.com/rest/v1/users/subaccount-username/login -H 'Content-Type: application/json' -d '{"password":"subaccount-password"}'

Result:

HTTP/1.1 200 OK
  Content-Type: application/json
  Set-cookie: saucelabs-login=...
  Set-cookie: ...

  {"cookies": ["saucelabs-login=...", ...]}

Access account details. ( Includes the number of minutes available. )

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/users/demo-user

Result:

{"access_key": "access-key", "minutes": "200", "id": "demo-user"}

Check account limits.

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/limits

Result:

{"concurrency": 10}

Create a new subaccount.

$ curl -X POST https://demo-user:access-key@saucelabs.com/rest/v1/users/demo-user -H 'Content-Type: application/json' -d '{"username":"subaccount-username", "password":"subaccount-password", "name":"subaccount-name", "email":"subaccount-email-address"}'

Result:

{"access_key": "subaccount-api-key", "minutes": 200, "id": "new-subaccount-username"}

Access current account activity.

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/activity

Result: ( Returns active job counts broken down by job status and subaccount )

{"subaccounts": {"demo-user": {"in progress": 25, "all": 30, "queued": 5}, "demo-subaccount": {"in progress": 5, "all": 5, "queued"0}}, "totals": {"in progress": 30, "all": 35, "queued": 5}}

Access historical account usage data. ( Optional query parameters 'start' and 'end' in YYYY-MM-DD format )

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/users/demo-user/usage

Result: ( Returns array of ['YYYY-MM-DD', [<jobs>, <seconds>]] pairs for each day that had activity )

{"usage": [["2011-3-18", [2, 38]], ["2011-3-31", [5, 5533]], ["2011-4-1", [7, 5076]]], "username": "demo-user"}

All URL's listed below are assumed to be against the base url of

https://username:access-key@saucelabs.com

Where username is your Sauce Labs username, access-key is the Sauce Labs access key you can find on your accounts page.

Jobs

• Attributes:
  • 'id': [string] Job Id
  • 'owner': [string] Job owner
  • 'status': [string] Job status
  • 'error': [string] Error (if any) for the job
  • 'name': [string] Job name
  • 'browser': [string] Browser the job is using
  • 'browser_version': [string] Browser version the job is using
  • 'os': [string] Operating system the job is using
  • 'creation_time': [integer] The time the job was first requested
  • 'start_time': [integer] The time the job began executing
  • 'end_time': [integer] The time the job finished executing
  • 'video_url': [string] Full URL to the video replay of the job
  • 'log_url': [string] Full URL to the Selenium log of the job
  • 'public': [string or boolean] Visibility mode [public, public restricted, share (true), private (false)]
  • 'tags': [array of strings] Tags assigned to a job
• List - List all job Id's belonging to a given user.
  • Relative URL: /rest/v1/:username/jobs
  • Method: GET
  • Authentication: required
  • Response fields: none
  • Parameters (optional):
    • [GET] limit -> displays the specified number of jobs, instead of truncating the list at the default 100.
    • [GET] full -> forces full job information to be returned, rather than just IDs.
    • [GET] skip -> skips the specified number of jobs.
    • [GET] from -> returns jobs since the specified time (in epoch time, calculated from UTC).
    • [GET] to -> returns jobs up until the specified time (in epoch time, calculated from UTC).

  • Examples:

    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs
    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs?limit=200
    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs?full=true
    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs?skip=20
    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs?from=1357747500&to=1357748700

• Show - Show the full information for a job given its ID.
  • Relative URL: /rest/v1/:username/jobs/id
  • Method: GET
  • Authentication: required
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs/01230123-example-id-1234

• Create - Jobs cannot be created via API. They must be created/started via the selenium client, such as SauceIDE, or the Selenium bindings for the language of your choice.
• Update - Changes a pre-existing job.
  • Relative URL: /rest/v1/:username/jobs/:id
  • Method: PUT
  • Authentication: required
  • Response fields:
    • name: [string] Change the job name
    • tags: [array of strings] Change the job tags
    • public: [string or boolean] Set job visibility to "public", "public restricted", "share" (true) or "private" (false)
    • passed: [boolean] Set whether the job passed or not on the user end
    • build: [int] The AUT build number tested by this test
    • custom-data: [JSON] a set of key-value pairs with any extra info that a user would like to add to the job
  • Parameters: none

  • Example:

    $ curl -X PUT https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs/01230123-example-id-1234 -H "Content-Type: application/json" -d '{"tags":["test","example","taggable"],"public":true,"name":"changed-job-name","passed": false, "custom-data":{"error":"step 17 failed"}}'

• Delete - Jobs cannot be deleted at all.
• Stop - Terminates a running job.
  • Relative URL: /rest/v1/:username/jobs/:id/stop
  • Method: PUT
  • Authentication: required
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl -X PUT https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs/01230123-example-id-1234/stop -d ''

• List Job Assets - Get a details about the static assets collected for a specific job.
  • Relative URL: /rest/v1/:username/jobs/:id/assets
  • Method: GET
  • Authentication: required
  • Response fields (each of these fields will be set to "null" if the specific asset isn't captured for a job):
    • sauce-log: [string] Name of the Sauce log recorded for a job
    • selenium-log: [string] Name of the selenium Server log file produced by a job
    • video: [string] Name of the video file name recorded for a job
    • screenshots: [array of strings] List of screenshot names captured by a job
  • Parameters: none

  • Example:

    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs/01230123-example-id-1234/assets

• Download Job Assets - You can download every asset created after your test runs on Sauce through our REST API. These include the video recording, Selenium log, and screenshots taken on crucial steps.
  • Relative URL: /rest/v1/:username/jobs/:id/assets/:file_name
  • Method: GET
  • Authentication: required
  • Parameters: none
  • 
    

    Available Files:

    • selenium-server.log
    • video.flv
    • XXXXscreenshot.png (where XXXX is a number between 0000 and 9999)
    • final_screenshot.png

  • Example:

    $ curl -O https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs/01230123-example-id-1234/assets/final_screenshot.png

Tunnels are used by Sauce Connect to redirect traffic for a given domain to a server on your internal network. They are unique to users and will not affect any other users. For more information, please read our Sauce Connect documentation

• Attributes:
  • 'id': [string] Tunnel ID
  • 'owner': [string] Tunnel owner
  • 'status': [string] Tunnel status
  • 'host': [string] Public address of the tunnel
  • 'creation_time': [integer]
• List - Retrieves all running tunnels for a given user.
  • Relative URL: /tunnels
  • Method: GET
  • Authentication: required
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/tunnels

• Show - Show the full information for a tunnel given its ID.
  • Relative URL: /tunnels/:id
  • Method: GET
  • Authentication: required
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/tunnels/01230123-example-id-1234

• Delete - Shuts down a tunnel given its ID.
  • Relative URL: /tunnels/:id
  • Method: DELETE
  • Authentication: required
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl -X DELETE https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/tunnels/01230123-example-id-1234

Informational REST commands do not require the username to be in the base URL. They are publicly available resources.

• Status - Returns the current status of Sauce Labs' services.
  • Relative URL: /info/status
  • Method: GET
  • Authentication: none
  • Response fields: none
  • Parameters: none

  • Examples:

    $ curl -X GET http://saucelabs.com/rest/v1/info/status

• Browsers - Returns an array of strings corresponding to all the browsers currently supported on Sauce Labs. (Choose the termination that defines which list you need, bearing in mind that Selenium 1 [RC] and 2 [WebDriver] are compatible with different browser/OS combinations.)
  • Relative URLs: /info/browsers/all, /selenium-rc, /webdriver
  • Method: GET
  • Authentication: none
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl -X GET http://saucelabs.com/rest/v1/info/browsers/webdriver

• Counter - Returns the number of test executed so far on Sauce Labs.
  • Relative URL: /info/counter
  • Method: GET
  • Authentication: none
  • Response fields: none
  • Parameters: none

  • Example:

    $ curl -X GET http://saucelabs.com/rest/v1/info/counter

This section is for use only by our partner programs, such as CloudBees accounts. If you use these commands with a standard account, they may cause unexpected behavior. To add and manage sub-accounts, head to your sub-accounts page.

Create a new subaccount, specifying a Sauce Labs service plan.

$ curl -X POST https://demo-user:access-key@saucelabs.com/rest/v1/users/demo-user -H 'Content-Type: application/json' -d '{"username":"subaccount-username", "password":"subaccount-password", "name":"sub-account-name", "email":"subaccount-email-address", "plan":"free"}'

Available plans: 'free', 'small', 'team', 'com', 'complus'

Result:

{"access_key": "subaccount-api-key", "minutes": 200, "id": "new-subaccount-username", "plan": "free"}

Update a subaccount Sauce Labs service plan.

$ curl -X POST https://demo-user:access-key@saucelabs.com/rest/v1/users/demo-user/subscription -H 'Content-Type: application/json' -d '{"plan":"small"}'

Unsubscribe a subaccount from it's Sauce Labs service plan.

$ curl -X DELETE https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/subscription

Sauce Labs provides temporary storage inside our network for mobile apps, Selenium jars, prerun executables, and other assets required by your tests. Storing assets in our network can eliminate network latency problems when sending big files to Sauce. Here's how you use our storage:

• - Before tests start, upload the file via our REST API as described below.
• - During tests, use a special URL for the file, in the following format: "sauce-storage:your_file_name"
• - Sauce will find the file, download it through our fast internal network and get your tests started right away

To upload the file via our REST API:

curl -u $SAUCE_USER:$SAUCE_KEY "http://saucelabs.com/rest/v1/storage/$SAUCE_USER/your_file_name" -X POST --data-binary @/path/to/your_file_name -v -H "Content-Type: application/octet-stream"

In case you want to upload a file again after it's been created, just add an 'overwrite' GET parameter with any value:

curl -u $SAUCE_USER:$SAUCE_KEY "http://saucelabs.com/rest/v1/storage/$SAUCE_USER/your_file_name?overwrite=yeah" -X POST --data-binary @/path/to/your_file_name -v -H "Content-Type: application/octet-stream"

This can be scripted in any programming language. Just make sure the HTTP method being used is POST and the Content-Type header is correct.

Please note that our temporary storage retains files for only 24 hours. We recommend users of this service upload files via our REST API every time their tests are about to run, as part of their build process.

Interacting with Jobs bug tracking system

Get list of available bug types

$ curl https://saucelabs.com/rest/v1/bugs/types

Result:

[{"id": "bug-type-example-id", "name": "Bug-example-name", "description": "Bug example description"}]

Get description of each field for a particular bug type

$ curl https://saucelabs.com/rest/v1/bugs/types/bug-type-example-id-1234

Result:

[{"type": "string", "name": "Field-name", "id": "Field-id"}, {"type": "int", "name": "Field-name", "id": "Field-id"}, ...]

Get detailed info for a particular bug

$ curl https://demo-user:access-key@saucelabs.com/rest/v1/bugs/detail/01230123-example-id-1234

Result:

{"Description": "Description of really nasty bug", "Title": "What a nasty bug", "ScreenshotEmbedURL": "https://saucelabs.com/jobs/01230123-example-id-1234/0001screenshot.png?auth=secret-auth-token", "CreationTime": 1234567890, "VideoEmbedURL": "https://saucelabs.com/bugs/01230123-example-id-1234?show_video=1&auth=secret-auth-token", "Job": "https://saucelabs.com/jobs/01230123-example-id-1234?auth=secret-auth-token", "BugEmbedURL": "https://saucelabs.com/bugs/01230123-example-id-1234?auth=secret-auth-token", "OS": "Linux", "Browser": "android 4."}

Get detailed info for a specified list of bugs

$ curl -G https://demo-user:access-key@saucelabs.com/rest/v1/bugs/query/ --data-urlencode 'ids=["01230123-example-id-1234", "0123401234-example-id-12345"]'

Result:

List of JSON objects containing detailed info on each queried bug id

Update bug id '01230123-example-id-1234' with specified key-value pairs

$ curl -G https://demo-user:access-key@saucelabs.com/rest/v1/bugs/update/01230123-example-id-1234 --data-urlencode 'update={"Property-name-1": "Property-Value-1", "Property-name-2": "Property-Value-2"}

Valid keys: Only following bug properties can be modified with the API: 'Title', 'Description'.

Result:

After successful command execution API will return {"status": "success"}