Manage test cases and suites with the API

Find a repository, create a manual test case, update it, and add it
to a test suite. Use a non-production project while building your integration.

1. Set up authentication

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

Send x-project-id on every request. The optional x-account-id header takes
an account UUID, and x-organization-id takes the organization ID. Your key's
user needs TestCase:Read, TestCase:Create, and TestCase:Update for the case
examples, plus TestSuite:Read and TestSuite:Update to find a suite and add
members. Creating a suite also needs TestSuite:Create.

Set KATALON_API_HOST, KATALON_API_KEY, and KATALON_PROJECT_ID from your
environment. This Bash helper passes the key to curl through standard input,
not through 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}" \
    "$@"
}

2. Choose a repository and an existing folder

Search repositories:

katalon_request "${KATALON_API_HOST}/v2/tm/repositories/search?page=0&size=100"

Choose a repository from content. Its id is the repository ID, called
testProjectId in write payloads. It is not the project ID in your header.
Choose a writable Cloud repository for this walkthrough. The older
repository list
returns an array instead of a page. With that older endpoint, specify types
explicitly: omitting types does not select all types and can return an empty
array even when repositories exist. Use types=CLOUD for Cloud repositories,
or all supported types as shown below. By default, both discovery endpoints
include only repositories with ACTIVE or ERROR status; the older list accepts
includeAllStatuses=true to include other statuses.

katalon_request "${KATALON_API_HOST}/v2/tm/repositories?types=GIT,KS,CLOUD"

Use the existing folder setup in the True Platform UI to choose a test-case
folder in that repository, for example Test Cases/Smoke, and a suite folder
such as Test Suites. Keep each complete folder path for the write payloads
below. This reference does not provide a folder discovery endpoint. If a later
folder mutation needs an existing folder ID, obtain it from your existing UI
setup; do not substitute a repository or project ID.

3. Create and read a test case

All changes below use
Publish test entities.
Save this payload as create-case.json. Replace 123 with the repository ID
and Test Cases/Smoke with the selected folder's complete path:

[
  {
    "testProjectId": 123,
    "testEntities": [
      {
        "action": "CREATE",
        "resource": "TEST_CASE",
        "data": {
          "name": "Customer sign-in",
          "path": "Test Cases/Smoke",
          "testType": "MANUAL",
          "steps": [
            {"description": "Sign in with a valid account", "expectedResult": "The dashboard opens"}
          ]
        }
      }
    ]
  }
]

katalon_request --request POST --header "Content-Type: application/json" \
  --data @create-case.json \
  "${KATALON_API_HOST}/v2/tm/repositories/test-entities?async=false"

Keep the returned testEntities[].data.id for this case as TEST_CASE_ID.
Use the actual returned ID, not the example IDs in this guide. If a response
contains taskResource.uuid but no created ID, do not submit dependent changes
or blindly retry the create; first establish whether the case was created.
A response can arrive before repository file publication finishes.

Read the case
to confirm its metadata:

katalon_request "${KATALON_API_HOST}/v2/tm/test-cases/${TEST_CASE_ID}"

4. Update the test case

Save this as update-case.json, replacing 123 and 456 with the repository
and test-case IDs:

[
  {
    "testProjectId": 123,
    "testEntities": [
      {
        "action": "UPDATE",
        "resource": "TEST_CASE",
        "data": {"id": 456, "description": "Verify that active customers can sign in."}
      }
    ]
  }
]

katalon_request --request POST --header "Content-Type: application/json" \
  --data @update-case.json \
  "${KATALON_API_HOST}/v2/tm/repositories/test-entities?async=false"

Read the case again to check the changed description. Omitted manual content
is preserved. If you replace steps or full manual content, send the complete
desired content, not only changed steps.

5. Add the case to a test suite

Search suites,
then select a manual suite in the same repository and keep its ID:

katalon_request "${KATALON_API_HOST}/v2/tm/test-suites/search?page=0&size=100"

To create a suite instead, publish a TEST_SUITE entity with action: CREATE
and data: {"name": "Smoke checks", "path": "Test Suites", "testSuiteTestType": "MANUAL"}.
Use your selected suite folder's complete path and keep the returned suite ID.

Save add-to-suite.json with the repository ID (123), suite ID (789),
and case ID (456):

[
  {
    "testProjectId": 123,
    "testEntities": [
      {
        "action": "ADD_TEST_CASES",
        "resource": "TEST_SUITE",
        "data": {
          "id": 789,
          "testSuiteItems": [{"testCaseId": 456, "versionSelectionType": "LATEST_VERSION"}]
        }
      }
    ]
  }
]

katalon_request --request POST --header "Content-Type: application/json" \
  --data @add-to-suite.json \
  "${KATALON_API_HOST}/v2/tm/repositories/test-entities?async=false"

ADD_TEST_CASES adds membership without replacing the existing list. In
contrast, suite UPDATE replaces the full membership list. Confirm membership
with the
suite membership search,
matching the returned testSuiteId and testCaseId across pages.

Next steps

Link a case to a requirement

Find an ALM-synchronized requirement with
requirement search
or its external key
(the requirement's sourceId, for example XQE-5).
Use its True Platform ID as REQUIREMENT_ID, not its external key. Linking needs
TestCase:Create; replace 456 below with your test-case ID:

katalon_request --request POST --header "Content-Type: application/json" \
  --data '{"testCaseIds":[456]}' \
  "${KATALON_API_HOST}/v2/tm/requirements/${REQUIREMENT_ID}/link-test-cases"

A requirement must have a synchronized external issue: a successful response
without one does not create coverage links. Links to the ALM issue may appear
after the next ALM sync; a successful response does not promise an immediate
linkedTestCaseCount change. To
unlink cases,
send the same JSON shape with DELETE, not POST.

Move or delete assets

The publishing reference
also covers rename, move, duplicate, and delete. Case and suite moves use a
destination parent path; folder moves use the complete destination path.
Folder changes can affect descendants. Review those effects and your permissions
before deleting or moving test assets.