# Virtuoso API

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

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 required to get what you need. Additionally, please review the relevant quotas, thresholds, and DoS protections mentioned here.

# API access

API requests are authenticated using an access token, which represents an authorization to access data on behalf of a user.

You can supply the token in one as an authorization header (e.g., Authorization: Bearer YOUR_TOKEN).

# Creating an API access token

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

While creating a token you can provide a note that helps you remember where the token will be used, and choose the token type that best fits your needs:

ALL provides full access to the system, limited only by the user´s role in the organization and access to projects;
BRIDGE provides read access for user´s organizations and manage access for user´s bridge instances.

Profile page — API tokens create

What do the access levels mean?

Read - can read data from the protected types of resources stored in Virtuoso (e.g., project the user has access to);
Write - can read and write data from/to the protected types of resources stored in the system (e.g., run executions, edit environments);
Manage - operations covered by the previous levels (read and write) and restricted/ownership reserved operations (e.g., control if users can publish journeys at goal level settings)

Independently of the access levels all tokens allow access to information that only needs a logged user (e.g., current user information).

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.

WARNING

API access tokens provide the same access as the password to your account. You should never share them with others and should store them securely to ensure they are not misused. See below for more detailed guidance, such as cases where a shared machine needs to access the Virtuoso API.

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

# Getting current user details for the token

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

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 apps, here are some of the interesting endpoints you can use to create 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 (executions) for your project;
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 executions

POST /api/goals/{goal_id}/execute executes all journeys belonging to the latest version of the given goal (latest goal snapshot). 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.

# Keeping tokens safe

We recommend that you keep API tokens secure by encrypting them where possible. As tokens are associated with users, they allow anyone with the token to perform actions on that user's behalf. We do not recommend sharing tokens or reusing the same token for different things. Keeping your tokens separate makes it easier to rotate them (for example if they are accidentally shared).

If you require an API token for the Bridge, we strongly recommend using the Bridge token type.

# Machine accounts

You may need to create tokens for automation (for example CI pipelines or the bridge on a shared virtual machine). In these cases we recommend creating an additional user in your organization that is dedicated for this purpose. This allows you to scope the access for the token; for example, if you only need to execute journeys in one project, you can grant access only to that project. This is especially important on shared machines where the token may be easily obtained.

To create an account for a machine user you will need an email address that you can use. Some email vendors allow aliases to be created (e.g. using [email protected]), although where possible we recommend using a shared inbox or group email to make administering the account easier. It is important to ensure that offboarding procedures address machine accounts to ensure that users who may possess the password or API keys can have their access revoked when necessary: when an authorized user leaves, then the password to the machine account should be reset.

# 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 app pipelines such as CircleCI, TravisCI, Azure Devops, Jenkins, etc.

You can use it by supplying the following arguments:

-t TOKEN: Personal access token of app 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 app user
  - -p PASSWORD: password of the app 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.

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.

← Overview Webhooks →