Visual API Endpoints
Use the Sauce Visual API to create builds, upload images, create snapshots, and finish builds from your own tooling. Unlike the other Sauce Labs APIs, the Visual API is a GraphQL API: you send every query and mutation to a single endpoint. Sauce Visual also stores the images you upload in regional Google Cloud Storage buckets, which you may need to allow in your firewall or proxy.
Refer to Getting Started for authentication and data center information. For a step-by-step example of a full Visual workflow, see API Lifecycle.
What You'll Need
- A Sauce Labs account (Log in or sign up for a free trial license)
- Your Sauce Labs username and access key
- Familiarity with GraphQL queries and mutations
GraphQL Endpoint
All Visual API operations, such as creating a build or a snapshot, go through one GraphQL endpoint. You choose the operation in the body of the request, not in the URL.
Send a GraphQL Request
POST /v1/visual/graphql
Parameters
query | | BODY | REQUIRED | STRING | The GraphQL query or mutation to run. |
variables | | BODY | OPTIONAL | OBJECT | Values for the variables used in the query or mutation. |
operationName | | BODY | OPTIONAL | STRING | The name of the operation to run, if the query contains more than one. |
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" \
--request POST 'https://api.us-west-1.saucelabs.com/v1/visual/graphql' \
--header 'Content-Type: application/json' \
--data '{"query": "<graphql-query>", "variables": {}}'
Endpoint by Data Center
Send requests to the endpoint for the data center your Sauce Labs account belongs to.
| Data Center | GraphQL Endpoint |
|---|---|
| Asia South | https://api.asia-south-2.saucelabs.com/v1/visual/graphql |
| Europe | https://api.eu-central-1.saucelabs.com/v1/visual/graphql |
| US East | https://api.us-east-4.saucelabs.com/v1/visual/graphql |
| US West | https://api.us-west-1.saucelabs.com/v1/visual/graphql |
Like the other Sauce Labs APIs, the Visual API is versioned in its URL. v1 is the current, stable version of the Visual API. See Versioning.
Image Storage Endpoints
Sauce Visual stores the images and DOM files you upload in Google Cloud Storage. When you upload an image, the createSnapshotUpload mutation returns a signed upload URL inside the storage bucket for your data center, and your client sends the file to that URL with a PUT request. If your network restricts outgoing traffic, allow the bucket for your data center so that uploads and downloads aren't blocked.
| Data Center | Storage Endpoint |
|---|---|
| Asia South | https://storage.googleapis.com/sauce-iris-prod-asia-south2-d5ub/* |
| Europe | https://storage.googleapis.com/sauce-iris-prod-europe-west3-ybyc/* |
| US East | https://storage.googleapis.com/sauce-iris-prod-us-east4-ybyc/* |
| US West | https://storage.googleapis.com/sauce-iris-prod-us-west4-ybyc/* |
The data center is part of each bucket name, using the Google Cloud region name, which differs from the Sauce Labs data center name. For example, the US West data center (us-west-1) stores images in the us-west4 bucket.
The /* at the end of each endpoint is a wildcard that stands for any file path in the bucket. It isn't a URL that you call. Use the full pattern in your firewall or proxy allowlist, so that every file in the bucket is allowed.
Use the storage endpoint and the GraphQL endpoint for the data center your Sauce Labs account belongs to. Using another data center's endpoints can cause slower uploads or access errors.
GraphQL Explorer
The GraphQL Explorer is an interactive, in-browser tool for the Visual API. Use it to browse the schema, including the available queries, mutations, and types, read the description of each field, and run test queries before you add them to your own tooling.
The Explorer requires authentication. To open it, sign in to Sauce Labs first, and then open the GraphQL endpoint in the same browser.
Step 1: Sign in to the Sauce Labs app with your Sauce Labs credentials.
Step 2: In the same browser, open the GraphQL endpoint for your data center, for example, https://api.us-west-1.saucelabs.com/v1/visual/graphql. See Endpoint by Data Center.
The interactive Explorer opens. If you open the endpoint without signing in to Sauce Labs, the request fails with an authorization error.