API Responses

This section describes how Apex Central responds to API requests.

After sending an authorization request to the intended API, Apex Central returns a JSON-formatted response object. The response format depends on the accessed resource.

General API Responses

Apex Central returns JSON-formatted responses and uses standard HTTP response codes.

Apex Central returns a JSON-formatted response object in the following format:

{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': (an object indicating the permissions assigned to the logged-on user account for accessing Apex Central features),
    'FeatureCtrl': (an object indicating the Apex Central deployment model),
    'SystemCtrl': (an object indicating the suspicious object distribution role of the Apex Central server)
}

The following table provides more information on certain fields in the response body.

Table 1. Response Body Fields

Field

Details

PermissionCtrl

  • permission: An integer indicating the permissions assigned to the logged-on user account

    • 255: Full control

    • 1: Read-only

  • elements: The value is always “null” or “None” for most Apex Central APIs.

FeatureCtrl

mode: An integer indicating the deployment model

  • 0: Apex Central as a Service

  • 1: Apex Central on-premises server

SystemCtrl

TmcmSoDist_Role: A string indicating the suspicious object distribution role

  • “edge”: Node server that sends suspicious object lists to the hub server

  • “hub”: Hub server that receives suspicious object lists from node servers

  • “none”: No distribution settings configured

The following table lists the possible responses.

Table 2. General API Responses

HTTP Status Code

Response Status

Response Body

200

Successful

 
{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result code of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': {'permission': '255', 'elements': None}, 
    'FeatureCtrl': {'mode': '0'}, 
    'SystemCtrl': {'TmcmSoDist_Role': 'none'}
}

400

Unsuccessful due to invalid parameters

 
{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result code of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': {'permission': '255', 'elements': None}, 
    'FeatureCtrl': {'mode': '0'}, 
    'SystemCtrl': {'TmcmSoDist_Role': 'none'}
}

401

Unsuccessful due to authorization error

 
{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result code of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': {'permission': '255', 'elements': None}, 
    'FeatureCtrl': {'mode': '0'}, 
    'SystemCtrl': {'TmcmSoDist_Role': 'none'}
}

500

Unknown error

 
{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result code of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': {'permission': '255', 'elements': None}, 
    'FeatureCtrl': {'mode': '0'}, 
    'SystemCtrl': {'TmcmSoDist_Role': 'none'}
}

Server and Security Agent API Responses

This section describes the JSON-formatted responses and standard HTTP response codes for Server and Security Agent APIs.

Apex Central returns a JSON-formatted response object in the following format:

{
 "result_code":(an integer indicating the result of this API call),
 "result_description":"(a string describing the result code)",
 "result_content":"(if provided, a JSON object representing the return value of the API)"
}
Important:

The result_description field in the response body is subject to change. If your application depends on Apex Central API responses, use the result_code value.

For a complete list of result_code status values, see API Result Codes.

The following table lists the possible responses.

Table 3. Server and Security Agent API Responses

HTTP Status Code

Response Status

Response Body

200

Successful

 
{
 "result_code":(an integer indicating the result of this API call),
 "result_description":"(a string describing the result code)",
 "result_content":"(if provided, a JSON object representing the return value of the API)"
}

400

Unsuccessful due to invalid parameters

 
{
 "result_code":(an integer indicating the result of this API call),
 "result_description":"(a string describing the result code)",
 "result_content":""
}

401

Unsuccessful due to authorization error

 
{
 "result_code":(an integer indicating the result of this API call),
 "result_description":"(a string describing the result code)",
 "result_content":""
}

500

Unknown error

 
{
 "result_code":(an integer indicating the result of this API call),   
 "result_description":"(a string describing the result code)",
 "result_content":""
}

API Result Codes

Apex Central uses standard HTTP response codes.

The following table lists the Apex Central Automation API result codes and the corresponding descriptions:

Result Code

Description

1

Operation successful

-2

Authentication unsuccessful: Authentication token not provided.

-3

Authentication unsuccessful: Malformed authentication token

-4

Authentication unsuccessful: Unsupported authentication token version

-5

Authentication unsuccessful: Invalid application ID

-6

Authentication unsuccessful: Authentication token expired

-7

Authentication unsuccessful: Invalid authentication token signature

-8

Authentication unsuccessful: Invalid request checksum

-9

Authentication unsuccessful: Unsupported authentication token signing algorithm

-21

Invalid input parameters

-22

Action invalid

-50

Unsupported HTTP method

-99

Internal server error

-102

Agent action unsuccessful: Multiple matches not supported

-103

Agent action unsuccessful: Unable to isolate agents reporting to another Apex Central server

-104

Agent action unsuccessful: Unable to connect to remote server

-105

Agent action unsuccessful: Target server not found

-106

Agent action unsuccessful: Target server managed by a child Apex Central server

-107

Agent action unsuccessful: Target server does not support command

-1101

Suspicious object action unsuccessful: Maximum quantity exceeded

-1102

Suspicious object action unsuccessful: Unable to generate Scan Prefilter for uploaded file, file likely to be blocked by antivirus