getStatusDocument

POST public/getStatusDocument

Returns the current status document for the edge security devices (ESDs) at a location. The status document is the latest report from each ESD: its overall status and the status of every application installed on it. You can identify the location by its location ID or by an ESD's serial number.

Request syntax

curl https://apiv2.acumera.net/public/getStatusDocument \
  --cookie av_session.txt \
  [--data-urlencode "location_id=<location_id>"] \
  [--data-urlencode "serial_number=<serial_number>"]

Supply location_id, serial_number, or both. The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required	Default value
`location_id`	Integer	The ID of the location. To find location IDs, use getCompanyInfo with `include_sites=1`.	One of `location_id` or `serial_number`
`serial_number`	String	The serial number of an ESD, for example `0041ac000003`. Returns the status document for that ESD only.	One of `location_id` or `serial_number`

Response syntax

{
    "success": "string",
    "data": {
        "<serial_number>": {
            "type": "string",
            "avid": "string",
            "timestamp": "string",
            "serial_number": "string",
            "customer_code": "string",
            "location_name": "string",
            "status": "string",
            "next_expected": "string",
            "apps": {
                "<application>": { "status": "string" }
            }
        }
    }
}

Response parameters

If the call succeeds, success is "1" and data has one entry for each ESD at the location, keyed by serial number. A site with a high-availability pair has two entries.

Field	Description
`type`	Always `status`.
`avid`	The location ID.
`timestamp`	When the ESD sent this report, as a Unix timestamp.
`serial_number`	The ESD's serial number.
`customer_code`	The company's customer code.
`location_name`	The location's name.
`status`	The overall status: `OK`, `INFO`, `WARNING`, `CRITICAL`, or `DOWN`. See Site status colors.
`next_expected`	When the next report is due, as a Unix timestamp.
`apps`	One entry per application on the ESD, keyed by its internal name (for example `MG2` for the ESD itself, `Clients` for devices, `FirewallLogger` for Network Traffic Analysis). Each entry has a `status` and fields specific to that application.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`API_NO_LOCATION_OR_SERIAL_NUMBER_SUPPLIED`	Either a location ID or a serial number must be supplied.	Neither parameter was sent.
`LOCATION_NOT_FOUND`	The location was not found.	No location has that ID, or no location has an ESD with that serial number.
`API_LOCATION_ID_SERIAL_NUMBER_MISMATCH`	The supplied location ID and serial number do not match.	Both were sent, and the ESD isn't at that location.
`AUTH_FAILED_FUNC_NOT_ALLOWED`	Authorization failed because you are not permitted to access the requested function.	Your account doesn't have access to the location.
`SITE_NOT_ACTIVE`	The location is not active.	The location isn't active.
`API_NO_RECORDS_FOUND`	No records found.	No status document is available.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Return the status document for a location

This example returns the status document for location 4510.

curl https://apiv2.acumera.net/public/getStatusDocument \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510"

Response (shortened to three applications and two devices):

{
    "success": "1",
    "data": {
        "0041ac000003": {
            "type": "status",
            "avid": "4510",
            "timestamp": "1793394966",
            "serial_number": "0041ac000003",
            "customer_code": "exmpl",
            "location_name": "Store 101",
            "status": "CRITICAL",
            "next_expected": "1793395266",
            "apps": {
                "MG2": {
                    "package_version": "PA4000",
                    "time_since_last_status": 300,
                    "status": "OK"
                },
                "Clients": {
                    "registered": [
                        {
                            "status": "OK",
                            "registered_name": "Office switch",
                            "ip": "10.169.254.2",
                            "device_type": "",
                            "mac": "00:00:5E:00:53:20",
                            "segment": "Switch",
                            "message": "Responding",
                            "policy": "Local",
                            "policy_description": "Local devices have local access only, no VPN, no Internet"
                        },
                        {
                            "status": "CRITICAL",
                            "registered_name": "Back room switch",
                            "ip": "10.169.254.3",
                            "device_type": "",
                            "mac": "00:00:5E:00:53:21",
                            "segment": "Switch",
                            "message": "Not Responding",
                            "policy": "Local",
                            "policy_description": "Local devices have local access only, no VPN, no Internet"
                        }
                    ],
                    "suspect": [
                        {
                            "status": "CRITICAL",
                            "mac": "00:00:5E:00:53:22",
                            "ip": "10.169.254.27",
                            "segment": "Switch",
                            "message": "Responding"
                        }
                    ],
                    "status": "CRITICAL"
                },
                "FirewallLogger": {
                    "status": "OK",
                    "mode": "FCL",
                    "logs_sent": "0",
                    "logs_failed": "0",
                    "logs_overlimit": "0",
                    "daily_limit": "Unlimited",
                    "dashboard": "Disabled",
                    "dash_url": "https://apps.sematext.com/ui/logs/<app_id>/0?query=..."
                }
            }
        }
    }
}

Example: Return the status document for one ESD by serial number

This example finds the location from the ESD's serial number. The response has the same format and contains only that ESD's entry.

curl https://apiv2.acumera.net/public/getStatusDocument \
  --cookie av_session.txt \
  --data-urlencode "serial_number=0041ac000003"

If you send both a location ID and a serial number that doesn't belong to that location, the call fails:

{
    "success": "0",
    "returnCode": "API_LOCATION_ID_SERIAL_NUMBER_MISMATCH",
    "returnMessage": "The supplied location ID and serial number do not match."
}