GET Workgroup

The IT Admin Agent leverages the Retrieve Workgroup List and Details API to automate Workgroup discovery, monitoring, and configuration validation within the Apex Platform. This enables zero-touch operations and improves administrative efficiency.

The API supports the following operations:

• Retrieve Workgroup Details

• Retrieve List of Workgroups

Retrieve Workgroup Details

External systems consume this API, including automation tools, AI agents, and integration services.

This endpoint retrieves the details of a specific Workgroup using its unique identifier (UID). Integrations, automation tools, and AI agents commonly use it to access Workgroup configuration and reference data.

Endpoint

GET /API/v1/Master/IM/Workgroup/{UID}

Endpoint Path Parameters

Request Headers

{
  "Accept": "application/json",
  "X-Api-Key": "{API_KEY}"
}

Sample Request

The request sends a GET call with a valid Workgroup UID and API credentials. Upon successful validation, the system fetches and returns the corresponding Workgroup record.

curl --location '{host}/API/v1/Master/IM/Workgroup/101' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'

Replace 101 with the required Workgroup UID, {API_KEY} with a valid API key, and {host} with the appropriate server address.

• Given a valid Workgroup UID or Value,

• The system sends a GET request with the UID or Value.

• The API returns the details of the specified Workgroup with HTTP 200 OK.

Sample Response

The response returns the details of the requested Workgroup along with execution statistics. A successful request returns HTTP 200 OK and includes the Workgroup UID and name in the response payload.

{
  "message": "1 Record(s) found.",
  "data": {
    "workgroup": [
      {
        "UID": 101,
        "Text": "Infrastructure Support"
      }
    ]
  },
  "executionTime": 0.10
}

Response Fields

Business Use Cases

Expected Result

• Returns HTTP 200 OK for a successful request.

• Returns the Workgroup record that matches the specified UID.

• Returns the Workgroup identifier and display name.

• Returns execution statistics when supported by the endpoint.

Retrieve List of Workgroups

External systems consume this API, including automation tools, AI agents, and integration services.

This endpoint retrieves all available Workgroup records configured within the IM module. It supports automation, reporting, monitoring, migration, and integration scenarios that require Workgroup master data.

Endpoint

GET /API/v1/Master/IM/Workgroup

Endpoint Parameters

This endpoint does not require any path or query parameters.

Request Headers

{
  "Accept": "application/json",
  "X-Api-Key": "{API_KEY}"
}

Sample Request

The request sends a GET call with valid API credentials to retrieve the complete list of Workgroups. This operation requires no path or query parameters.

curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'

Replace {API_KEY} with a valid API key and {host} with the appropriate server address.

• Given that the GET Workgroup List API is available,

• The system sends a valid GET request.

• The API returns all available Workgroups with the expected response structure and HTTP 200 OK.

Sample Response

The response returns a collection of Workgroup records along with the total number of records found and execution time.

{
  "message": "2 Record(s) found.",
  "data": {
    "workgroup": [
      {
        "UID": 101,
        "Text": "Infrastructure Support"
      },
      {
        "UID": 102,
        "Text": "Application Services"
      }
    ]
  },
  "executionTime": 0.12
}

Given that the API returns a successful response, the response payload conforms to the defined API schema and includes the following fields:

• message

• data

• workgroup

• UID

• Text

• executionTime

Response Schema

{
  "message": "string",
  "data": {
    "workgroup": [
      {
        "UID": "integer",
        "Text": "string"
      }
    ]
  },
  "executionTime": "number"
}

Response Fields

Business Use Cases

Expected Result

• Returns HTTP 200 OK.

• Returns all available Workgroup records configured within the IM module.

• Returns the unique identifier and display name of each Workgroup.

• Returns the record count and execution time when supported by the endpoint.

Error Messages for Record Details and List

401 Unauthorized

The system cannot authenticate the request because valid API credentials were not provided or have expired.

The following request does not include the required X-Api-Key header:

curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json'

{
  "message": "Unauthorized access.",
  "errorCode": 401,
  "details": "Valid API credentials are required."
}

403 Forbidden

The caller has authenticated, but the associated user, agent, or service account does not have permission to access Workgroup records.

The following is Valid API Key Without Workgroup Access:

curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {VALID_API_KEY_WITHOUT_WORKGROUP_ACCESS}'

{
  "message": "You do not have permission to access Workgroup records.",
  "errorCode": 403,
  "details": "The authenticated caller lacks the required privileges to perform this operation."
}

404 Not Found

The specified Workgroup record does not exist or is unavailable in the system. This response can also occur when the endpoint path is incorrect.

The following request attempts to retrieve an Workgroup record with the record ID 9999:

curl --location '{host}/API/v1/Master/IM/Workgroup/9999' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'

{
  "message": "Workgroup record not found.",
  "errorCode": 404,
  "details": "No Workgroup record was found for the specified UID."
}