API ReferenceDeveloper GuidesRecipesDocumentationCommunityAcademyPlatform
Developer Guides

Find shared TestCloud environments with the API

Use the shared TestCloud catalog to find desktop-browser and mobile-device
environments for automation or manual testing, then read artifacts from an
existing session with the v1 output endpoints. This guide does not cover
private-device discovery, requests with available=true, or starting a test session.

1. Set up authentication

Use your tenant host, https://<tenant>.katalon.io, with no trailing slash.
Authenticate with HTTP Basic: use an empty username and your Katalon API key
as the password. See the
authentication reference
for API-key setup. Keep the key in your secret store and do not enable shell
tracing (set -x).

Send x-project-id on every request. For the environment catalog, the key's
user needs Execution:Read in that project. For session outputs:
You can read the sessions of organizations you belong to.
You can also send x-account-id (account UUID) and
x-organization-id (organization ID) when needed to select your context.
These headers do not grant permissions by themselves.

Set KATALON_API_HOST, KATALON_API_KEY, and
KATALON_PROJECT_ID from your environment. The Bash helper below passes
credentials to curl through standard input rather than process arguments.
If the key contains " or \, escape those characters as \"
and \\ for curl's configuration format.

katalon_request() {
  : "${KATALON_API_KEY:?Missing API key}"
  printf 'user = ":%s"\n' "${KATALON_API_KEY}" |
  curl --config - --silent --show-error --fail-with-body \
    --header "x-project-id: ${KATALON_PROJECT_ID:?Missing project ID}" \
    --header 'Accept: application/json' \
    "$@"
}

2. List the shared catalog

List shared TestCloud environments:

katalon_request \
  "${KATALON_API_HOST:?Missing tenant host}/v2/tc/ees/environments?available=false&includePrivate=false"

The request has no body. Keep available=false and includePrivate=false
for the shared catalog in this section. Those values define the use case
covered here; they do not mean the service rejects other values.
available=false skips availability filtering and manual availability lookup.
Automation availability can still be looked up and included in the response.

Read entries from the response's items array. For each entry:

  • id identifies the environment. Treat it as an opaque value.
  • platform, platformName, and platformVersion describe the platform.
  • Desktop entries can have browser, browserName, browserVersion, and
    browserVersionType.
  • Mobile entries can have device information such as deviceName,
    deviceDisplayName, and formFactor.
  • capabilities.automation.supported and capabilities.manual.supported
    describe testing support. Do not assume an absent value means true.

The catalog is not a capacity reservation. An entry does not guarantee that
execution capacity is immediately available.

3. Narrow the catalog

Set type=automation to request automation capabilities, or type=manual
for manual-testing capabilities. Omit it to request both, in which case entries
missing either capability group are excluded; this is not the union of the
automation and manual catalogs. To find shared
desktop-browser environments for automation, use a URL-encoded q filter:

katalon_request --get \
  --data-urlencode 'available=false' \
  --data-urlencode 'includePrivate=false' \
  --data-urlencode 'type=automation' \
  --data-urlencode 'q=type==desktop_browser' \
  "${KATALON_API_HOST}/v2/tc/ees/environments"

Use q=type==mobile_device to select shared mobile-device entries instead.
The query option type selects the testing capability; the type field
inside q selects the environment category.

This endpoint does not provide a paginated response: there is no total or
continuation token. It reads the first 5000 matching catalog records before
capability filtering. Omit pageToken and size; they are not working pagination
controls. The service overrides them for this catalog read, so size does not
limit the returned items.

4. Read session artifacts and download links (v1)

Use an existing TestCloud session ID as KATALON_SESSION_ID. These output
reads use /v1/tc/ees/sessions; there are no v2 output aliases in this reference.
Both GET requests have no body and use the same empty-username API-key helper.

List session outputs
with exact uppercase action=DOWNLOAD to prepare download links:

katalon_request \
  "${KATALON_API_HOST}/v1/tc/ees/sessions/${KATALON_SESSION_ID:?Missing session ID}/outputs?action=DOWNLOAD"

The JSON object contains sessionId and an outputs array. An empty array
means the session has no output records and is an expected response, not an
error. Each output can contain string fields id, type, name, and value.
Do not assume a fixed set of output types. Without action=DOWNLOAD, or with
another action value, the list leaves stored values unchanged.

Set KATALON_OUTPUT_ID to an output's id to
read one output:

katalon_request \
  "${KATALON_API_HOST}/v1/tc/ees/sessions/outputs/${KATALON_OUTPUT_ID:?Missing output ID}"

The detail read always prepares value for download; it does not need an
action query. During preparation, values containing s3:// become signed
download URLs; other values remain unchanged. Neither response contains file
bytes. Fetch a returned HTTP(S) download URL separately, without the
katalon_request helper: do not send your Katalon API key to the download host.
Treat signed links as sensitive and keep them out of logs and shared examples.

Next steps

Updated about 8 hours ago

Did this page help you?