Sauce REST API

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 sub-account to saucelabs.com and retrieve login cookies:

$ curl -D - -X POST https://demo-user:access-key@saucelabs.com/rest/v1/users/sub-account-username/login -H 'Content-Type: application/json' -d '{"password":"sub-account-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 -v 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 -v https://demo-user:access-key@saucelabs.com/rest/v1/limits

Result:

{"concurrency": 10}

Create a new sub-account.

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

Result:

{"access_key": "sub-account-api-key", "minutes": 200, "id": "new-sub-account-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/rest/v1/username/jobs

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': [boolean] Public job?
  • 'tags': [array of strings] Tags assigned to a job
• List - List all job Id's belonging to a given user.
  • Relative URL: /jobs
  • Method: GET
  • Authentication: required
  • JSON fields: none
  • Parameters:
    • [GET] full (optional) -> forces full job information to be returned rather than just Id's.

  • Example:

    $ curl -v https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs
    $ curl -v https://demo-user:access-key@saucelabs.com/rest/v1/demo-user/jobs?full=true

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

  • Example:

    $ curl -v 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: /jobs/:id
  • Method: PUT
  • Authentication: required
  • JSON fields:
    • name: [string] Change the job name
    • tags: [array of strings] Change the job tags
    • public: [boolean] Set job to public/non-public
    • passed: [boolean] Set wether 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 -v -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"}'

• Delete - Jobs cannot be deleted at all.
• Stop - Terminates a running job.
  • Relative URL: /jobs/:id/stop
  • Method: PUT
  • Authentication: required
  • JSON fields:
    • name: [string] Change the job name
    • tags: [array of strings] Change the job tags
    • public: [boolean] Set job to public/non-public
  • Parameters: none

  • Example:

    $ curl -v -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"}'

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
  • JSON fields: none
  • Parameters: none

  • Example:

    $ curl -v 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
  • JSON fields: none
  • Parameters: none

  • Example:

    $ curl -v 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
  • JSON fields: none
  • Parameters: none

  • Example:

    $ curl -v -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 publically available resources.

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

  • Examples:

    $ curl -v -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.
  • Relative URL: /info/browsers
  • Method: GET
  • Authentication: none
  • JSON fields: none
  • Parameters: none

  • Example:

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

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

  • Example:

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

Create a new sub-account, 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":"sub-account-username", "password":"sub-account-password", "name":"sub-account-name", "email":"sub-account-email-address", "plan":"free"}'

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

Result:

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

Update a sub-account 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 sub-account from it's Sauce Labs service plan.

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