Legacy Files and Visual Checkpoints API (v1)

Use the legacy /api/v1 routes to read file handles, allocate file upload
destinations, read visual checkpoint details, update a checkpoint review
status, or rename a baseline collection group.

1. Set up authentication

Send requests to your tenant host, https://<tenant>.katalon.io, with no
trailing slash. Append the /api/v1 path shown in each request. The {tenant}
placeholder is your tenant subdomain.

Authenticate with a Katalon API key using HTTP Basic with an empty username
and the key as the password. Keep the key in your CI secret store. Do not turn
on shell tracing (set -x). Resource and project access checks still apply;
authentication alone does not grant access to every file or checkpoint.

Set KATALON_API_HOST, KATALON_API_KEY, and the project and resource IDs used
below from your CI variables and secrets. The helper passes the API key to curl
through standard input, not through a process argument. If a key contains "
or \, escape those characters as \" and \\ in 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 "$@"
}

2. Read a file handle

The id in the file route is a file-handle ID. A cloud-storage response
redirects to a signed download destination; some deployments stream file bytes
directly. To inspect the first response headers without following a redirect:

umask 077
katalon_request --dump-header download-headers.txt --output /dev/null \
  "${KATALON_API_HOST}/api/v1/files/${FILE_ID:?Missing file-handle ID}"

Do not add -L to this request. If the response is 302, inspect its Location
header in the private download-headers.txt file, then make a separate plain GET to that returned destination without the
API key. The signed destination is a private capability: do not print it to
shared logs or send it to anyone else. If the response is 200, request the
route again with curl's --output option to save the streamed bytes. A matching
If-None-Match value returns 304 with no body in direct-stream mode. The
stream response supplies the file hash as ETag and an attachment filename as
Content-Disposition; its MIME type depends on the file.

See Download a file by file-handle ID.

3. Allocate upload destinations

GET /api/v1/files/upload-urls requires the project ID and the number of
destinations in the query string. This route does not use a project header.
Use a small positive count such as 1; no maximum is established here, and a
non-positive count returns an empty array.

katalon_request --output upload-destinations.json \
  "${KATALON_API_HOST}/api/v1/files/upload-urls?projectId=${PROJECT_ID:?Missing project ID}&numberUrl=1"

The private upload-destinations.json file contains a direct JSON array of metadata for fresh destinations, including a
path and a private signed uploadUrl. Use that destination for a PUT only.
Do not send the API key to its host, and do not store or share the signed URL in
logs. The API key is used for the allocation request, not the file transfer.
This only allocates destinations; it does not import an execution report or
complete a reporting workflow. Remove the private metadata files when finished.

See Allocate file upload URLs.

4. Read checkpoint pixel details

For GET /api/v1/checkpoint-pixels/{id}, {id} is the checkpoint ID, not a
checkpoint-pixel ID. Use the checkpoint ID from the visual-testing workflow:

katalon_request \
  "${KATALON_API_HOST}/api/v1/checkpoint-pixels/${CHECKPOINT_ID:?Missing checkpoint ID}"

The response contains standard pixel-comparison details and related checkpoint
assets. The standard read does not return temporary pixel records.

See Get checkpoint pixel details.

For both file-handle and checkpoint-pixel reads, an unknown ID can return
HTTP 500 with a message beginning “Either this resource does not exist…”.
Check the resource ID and your access before retrying.

5. Set a checkpoint review status

Send the status as the required query parameter. The operation has no request
body and returns 204 with no response body:

katalon_request --request POST \
  "${KATALON_API_HOST}/api/v1/checkpoints/${CHECKPOINT_ID:?Missing checkpoint ID}/resolve?status=PASSED"

Supported values are UNRESOLVED, PASSED, and FAILED. UNRESOLVED resets
the review status. The operation marks the checkpoint and its containing
visual execution as unsaved; it does not save a baseline or start another
analysis.

See Set a checkpoint review status.

6. Rename a baseline collection group

The request body uses only the new name. The group name must contain a
non-whitespace character and be no longer than 256 Java characters. If the
access-control feature that checks sourceRequest is enabled, include
sourceRequest=G2 or sourceRequest=G3; otherwise the parameter is ignored.
It is not authentication.

katalon_request --request PUT \
  --header "Content-Type: application/json" \
  --data '{"name":"Baseline refresh"}' \
  "${KATALON_API_HOST}/api/v1/baseline-collection-groups/${GROUP_ID:?Missing group ID}?sourceRequest=G3"

The response is the group's basic resource. It includes creator attribution
and basic latest-version details; this operation does not replace baseline
assets or run configurations.

See Rename a baseline collection group.