# Virtuoso API

Virtuoso's internal API can be used to integrate Virtuoso with external solutions.

Beta API interface

While this document helps you to get through the basics with Virtuoso's API, the API interface and the data provided are subject to change and will be replaced with the upcoming public external API.

API Documentation

Virtuoso's REST API documentation is available here. If you want to use our API and have any questions, please reach out directly to us and we will help you get set up and point you to the interfaces you need to get what you need.

# API access

Virtuoso API is only available for authorized users. Thus, API requests must provide an access token, which represents an authorization to access data on behalf of a user.

You can supply the token in one of the following ways:

  • As authorization header (e.g., Authorization: Bearer YOUR_TOKEN)
  • As basic auth (note that for basic auth, the token needs to be base64 encoded e.g., Authorization: Basic ZjQwM2FhZjItNmY5MC00YjY1LWIwYzYtODE4MDhmOTk0YWI3)
  • As a query string (e.g., by supplying ?token=$YOUR_TOKEN in the URLs). this method is not recommended

# Creating an API access token

You can create permanent API access tokens from your Profile page, in the API tokens tab:

Profile page — API tokens tab

While creating a token you have to provide a note that helps you remember where the token will be used.

For security reasons, the access token is only shown to you at the time of its creation. You should copy the value and store it in a secure location so that you can use it when needed.

You can at any time delete a token by clicking on icon near it. After confirming the operation, Virtuoso will no longer accept requests that use that specific token.

Getting a time-limited access token

As an alternative, you can perform a POST request to the login endpoint, and store the token in an environment variable named TOKEN, as exemplified bellow. Note that this example uses jq to parse the JSON response. Though this is not necessary to use the Virtuoso API.

export TOKEN=$(curl -s -X POST -H "Content-Type: application/json" -d '{ "email": "<email>", "password":"<password>"}' "https://api.virtuoso.qa/api/auth/login?envelope=false" | jq -r .token)


API access tokens can be used to trigger actions in Virtuoso. Please, keep them secure and be careful with whom you share them with.

The rest of this document assumes that you already have a permanent token or the TOKEN environment variable set.

# Getting the logged user details

Using a permanent or time-limited access token, you can perform a GET request to the /user endpoint:

curl --header "Authorization: Bearer $TOKEN" https://api.virtuoso.qa/api/user

Alternatively, we can pass the token in the URL. The previous example would become:

curl https://api.virtuoso.qa/api/user?token=<token>

Notice the `API` environment

Notice that the address for the Virtuoso API (e.g., api.virtuoso.qa) is different from the application address (e.g., app.virtuoso.qa).

# Useful endpoints

For the purpose of creating integrations, here are some of the interesting endpoints you can use to create explorations/executions, and retrieve relevant project data. See the full API documentation →

# Retrieving projects and data

  • GET /api/projects returns a list of projects you can access;
  • GET /api/projects/{project_id}/goals returns a list of goals in your project;
  • GET /api/projects/{project_id}/jobs returns a list of active jobs for your project (explorations/executions);
  • GET /api/projects/{project_id}/snapshots returns a list of snapshots within the project (though each goal already will return with a list of available snapshots it has);

# Launching explorations, executions and snapshot comparisons

# Launching explorations

POST /api/goals/{goal_id}/explore launches an exploration on the given goal. For example:

# Explore goal with ID 42
curl --header "Authorization: Bearer $TOKEN" -X POST https://api.virtuoso.qa/api/goals/42/explore

# Launching snapshot comparisons

Once you have a snapshot of your application and/or built your application using a mix of exploration and synchronisation after adding steps manually, you may want to capture snapshots of it in your CI pipeline.

POST /api/goals/{goalId}/snapshots/{snapshotId}/sync_graph starts snapshot testing (i.e., synchronising your graph with the application). For example:

# Start snapshot testing goal 42 with latest snapshot ID of 7
curl --header "Authorization: Bearer $TOKEN" -X POST https://api.virtuoso.qa/api/goals/42/snapshots/7/sync_graph

# Launching executions

POST /api/goals/{goal_id}/execute executes all journeys belonging to the latest snapshot of the given goal. For example:

# If you want to execute ALL journeys in goal with ID 42
curl --header "Authorization: Bearer $TOKEN" -X POST https://api.virtuoso.qa/api/goals/42/execute

# If you want to execute journeys from a specific snapshot, you can add /snapshots/{snapshot_id}
curl --header "Authorization: Bearer $TOKEN" -X POST https://api.virtuoso.qa/api/goals/42/snapshots/7/execute
# Supplying initial variable data

Sometimes you may already have initial context data, or variables that you want to set at the time of starting your execution. To achieve this, you can provide the initialData as POST data to the API as per the example below. (note: this assumes that you have already have test steps with variables)

  # Execute journeys from goal 42, and set initial data of variables $myToken to "123" and $startingUrl to "https://spotqa.com"
  curl --header "Authorization: Bearer $TOKEN" -X POST -H "Content-Type: application/json" -d '{ "initialData": { "myToken":123, "fullName": "SpotQA Virtuoso" } }' https://api.virtuoso.qa/api/goals/42/execute
# Supplying custom HTTP headers

Sometimes you may wish to set custom HTTP headers to your application, for example, to trigger test attributes on your server. You can achieve this by supplying httpHeaders in your request. Note that this is not supported for cross-browser/device executions.

  # Execute journeys from goal 42, and set custom http headers on the requests
  curl --header "Authorization: Bearer $TOKEN" -X POST -H "Content-Type: application/json" -d '{ "httpHeaders": { "myToken":123, "fullName": "SpotQA Virtuoso" } }' https://api.virtuoso.qa/api/goals/42/execute
# Executing against a different environment

If you want to execute your current journeys against a different environment (e.g., your goal URL is against staging, but you want to execute your tests against production), you can supply a custom starting url for your journey using startingUrl; for example:

  # Execute journeys from goal 42, and set the first navigation step to "https://spotqa.com"
  curl --header "Authorization: Bearer $TOKEN" -X POST -H "Content-Type: application/json" -d '{ "startingUrl": "https://spotqa.com/" }' https://api.virtuoso.qa/api/goals/42/execute

Starting url

Providing a startingUrl does not override a data-driven navigation step. Only the first navigation step matching the goal URL is going to get updated. A startingUrl can also be combined with initial variable data.

# Example script

Here is a prepared sample script that can execute journeys of a goal using the API: ./execute.sh.

This can be used in many execution-based integration pipelines such as CircleCI, TravisCI, Azure Devops, Jenkins, etc.

We strongly advise that you create a specific user for integration purposes (and inviting them to relevant projects), and use the personal token from that user to make API calls. This enables you to limit the scope/access of the user to the projects/permissions you want, rather than using your own access token with full access.

You can use it by supplying the following arguments:

  • -t TOKEN: Personal access token token of integration user (as shown above)
    • As an alternative for quick testing purposes, you can pass your login details (not recommended):
      • -u EMAIL: email account of the integration user
      • -p PASSWORD: password of the integration user
  • --goal_id 1234: ID of the goal you wish to execute (you can find this from the URL of the goal)
  • (optional) --snapshot_id 4321: If not the latest snapshot, you can specific an exact snapshot here.
  • (optional) --staging: if you wish to execute against the staging environment

Credentials as environment variables

Rather than passing the token as argument, you can set them as environment variable VIRTUOSO_TOKEN.

For any questions on how to extend this, or if you need help to make other API calls, please contact the customer success team.

Last Updated: 2/8/2021, 2:57:12 PM