Find organizations with the API

List organizations in an account, read organization details, and update an
organization's name or logo value. Use a non-production account and project.

1. Set up authentication and context

Send requests to your tenant host, https://<tenant>.katalon.io, over HTTPS.
Use HTTP Basic with an empty username and your Katalon API key as the
password. See Authenticate with the v2 API.
Keep your key in a secret store. Do not enable shell tracing (set -x).

Send these headers on every request:

The account UUID in x-account-id differs from the numeric accountId field.
A project ID is not a repository ID. See Know which ID is which.
Headers select context; they do not grant permission.

Set KATALON_API_HOST, KATALON_API_KEY, KATALON_ACCOUNT_ID, and
KATALON_PROJECT_ID in your environment or secret store. This helper passes the
key to curl through standard input, not process arguments. Escape " and \
in the key 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-account-id: ${KATALON_ACCOUNT_ID:?Missing account UUID}" \
      --header "x-project-id: ${KATALON_PROJECT_ID:?Missing project ID}" \
      "$@"
}

2. List organizations

Call GET /v2/admin/organizations to list non-archived organizations in the
account selected by x-account-id. The response uses data and total.

The optional accountId filter takes one numeric value and uses EQ only. An
omitted operator defaults to EQ. Do not use a string, list, or another
operator for this field. This filter only narrows the account selected by
x-account-id. If you do not know the numeric account ID, omit this filter.

Set KATALON_ACCOUNT_NUMERIC_ID to the numeric account ID. It is not the UUID
in x-account-id.

katalon_request --get "${KATALON_API_HOST:?Missing tenant host}/v2/admin/organizations" \
  --data-urlencode 'query={"filters":[{"field":"accountId","operator":"EQ","value":'"${KATALON_ACCOUNT_NUMERIC_ID:?Missing numeric account ID}"'}],"sorts":[{"field":"id","desc":false}],"offset":0,"limit":20}'

To list all organizations in the selected account, omit the accountId filter.
Use the id from data to read one organization. total counts all matching
organizations before pagination.

3. Read organization details

Call GET /v2/admin/organizations/{id} with a numeric organization ID from the
list response:

katalon_request \
  "${KATALON_API_HOST:?Missing tenant host}/v2/admin/organizations/${ORGANIZATION_ID:?Missing organization ID}"

The response contains one organization under data. This lookup can return an
archived organization, unlike the collection list.

4. Update an organization's name or logo value

Call PUT /v2/admin/organizations/{id} with optional name and logo fields.
Send a nonblank name. Omitted or null values preserve their current values;
they do not clear them.

katalon_request --request PUT \
  "${KATALON_API_HOST:?Missing tenant host}/v2/admin/organizations/${ORGANIZATION_ID:?Missing organization ID}" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Example organization updated","logo":"example-logo-reference"}'

Send a logo string only when you already have the value to set. This endpoint
does not define a logo upload step. The response contains the updated
organization under data.