Byte25 API Reference
Byte25 API Reference
Version: 2.5.3
Last Updated: December 2025
Contents
Assets
Asset Update (/api/assetUpdate)
Asset Action Update (/api/assetActionUpdate)
Get Asset Action Data (/api/getAssetActionData)
Data Extraction API Calls
Top X Volume Query (/api/getTopXData)
Time Series Volume Query (/api/getTimeSeriesData)
SNMP
Set SNMP Device (/api/setSNMPDevice)
Get SNMP Device Info (/api/getSNMPDevice)
Get SNMP Volume Data (/api/getSNMPVolumeData)
Overview
The Byte25 API provides access to all data stored on the Byte25 cloud servers. The API is organized around REST. The API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The API uses long lived API keys to authenticate requests to access data from the relevant Byte25 cloud servers. Each API key is associated with a specific customer tenancy.
Authentication
The Byte25 API uses API keys to authenticate requests.
The API key is available from the Byte25 Cloud Dashboard. For users with admin privilidges, the API key is available from the Admin->API Key menu otopn. (The Admin menu is accessed from the ellipsis icon on the top right of the dashboard screen). Contact Byte25 support if you need assistance accessing your API key of need a manually genearted key.
The API key is linked to a specific customer tenancy configured on the relevant Byte25 cloud server. That is, a single key can only access data for a single customer tenancy. If you are a service provider managing multiple customer tenancies, you will need a different API key for each customer.
With API key auth, a key-value pair is set in the request header. The key value pair is of the format:
Key: “byte25”
Value: <API string>
To test the API key is working correctly, you can use curl with the Byte25 checkStatus API call:
curl -X GET ‘https:<byte25cloudserver URL>/api/checkStatus’ -H ‘byte25:<API string>’
If successful, the response should look like:
{
“sysStatus”:1,
“elasticsearch”:2,
“byte25server”:1,
“suricata”:0,
“dpi”:0,
“netflow”:0,
“correlator”:0
}
Running API Calls using CURL
Most of the Byte25 API calls are POST requests with the POST body containing the relevant parameters for the specific API call. Requests can be made using multiple methods including CURL and utilities such as Postman. This section provides an example of how to run a POST command with body using CURL.
The CURL command format is as follows:
curl -X POST -H ‘byte25:<API String>’ -H ‘Content-Type: application/json’ -d ‘<JSON Object>’
For example:
curl -X POST ‘https://<cloud URL>/api/getSNMPVolumeData?pretty=true’ \
-H ‘byte25:<API key>’ \
-H ‘Content-Type: application/json’ \
-d ‘{“time”: {“format”:”daterel”,”range”:”h”,”value”:24}}’
This should return SNMP data for the last 24 hours in CSV format.
Assets
Get Assets (/api/getAssets)
Description
Returns assets matching search criteria from the assetdb index. This is typically used to return all endpoints or all appliances, however the match criteria can be any field in the asset object.
Request Body
Property |
Type |
Description |
| matchArr | <object> | The fields on with the search for the existing Elastic document. |
matchArr and updateArr format:
Property |
Type |
Description |
| field | <string> | Name of the property to match on or update |
| value | <string> | Value of the property to match on or update |
Post Body Example
{
matchArr: [
{
field: ‘agentType’,
value: ‘appliance’
}
]
}
Response
The response is a standard status object with the data being an array of asset objects. Refer to AssetDB Structure for more detail on specific asset objects.
Status Object:
Property |
Value |
| status | <string> success or error |
| msg | <string> Success or Error message |
| data | <JSON Obj> Asset Array |
Delete Assets (/api/delAssets)
Description
Deletes one or more assets matching search criteria from the assetdb index. Normally used to delete individual or specific assets but capable of deleting multiples
Request
POST /<target>/api/delAsset
Request Body
Property |
Type |
Description |
| matchArr | <object> | The fields on with the search for the existing Elastic document. |
matchArr and updateArr
Property |
Type |
Description |
| field | <string> | Name of the property to match on or update |
| value | <string> | Value of the property to match on or update |
Post Body Example
{
matchArr: [
{
field: ‘agentType’,
value: ‘appliance’
},
{
field: ‘machine_id’,
value: ‘366255418’
}
]
}
Response
The response is a standard status object with a message of how many assets were deleted or alternative the cause of any error.
Status Object:
Property |
Value |
| status | <string> success or error |
| msg | <string> Success or Error Message |
Asset Update (/api/assetUpdate)
Description
Add or update entry to assetdb Elastic index. This typically used to add an assetdb entry or alter fields for a specific assetdb entry. For example, altering the action field for an individual appliance or endpoint. Use assetActionUpdate to alter multiple devices, such as all appliances or all endpoints.
Note: The add option first checks to see if there is an existing asset matching the new one being added. If an asset document already exists it will be deleted before the new object is added to assetdb. For endpoints and appliances, the matching criteria is based on the fields agentType, cust_id and machine_id. For snmp devices the matching criteria is agentType, cust_id and local_ip
Request
POST /<target>/api/assetUpdate
Request Body
Property |
Type |
Description |
| action | <string> | Either update or add |
| type | <string> | Type of asset < appliance | endpoint | snmp_device > |
| matchArr | <object> | The fields on with the search for the existing Elastic document. Also used for the update_by_query Elastic API (only for update) |
| updateArr | <object> | The fields for which to update the existing Elastic document. Also used for the update_by_query Elastic API (only for update) |
| assetObj | <object> | Asset object to be inserted. Refer to AssetDB Structure for asset object structure (only for insert) |
matchArr and updateArr
Property
Property |
Type |
Description |
| field | <string> | Name of the property to match on or update |
| value | <string> | Value of the property to match on or update |
Post Body Example
{
“action”: “update”,
“matchArr”: [
{
“field”: “machine_id”,
“value”: “886f52fcaadd”
}
],
“updateArr”: [
{
“field”: “action”,
“value”: “processstatus”
}
]
}
Response
The response is a standard status object with a message of how many assets were deleted or alternative the cause of any error.
Status Object:
Property |
Value |
| status | <string> success or error |
| msg | <string> Success or Error Message |
Asset Action Update (/api/assetActionUpdate)
Description
Updates the action in the assetdb index for appliances or endpoints. This is a bulk change that will set the action for all endpoint or all appliances or both. This API call is called when changes are made to appliance configs that need to be pushed to multiple devices. For example, when new synthetic transactions or threat detection suppression rulls are added.
If the action is set in assetdb, then on the device next poll, the new action will be sent to the appliance or endpoint to be executed. This is the mechanism by which we can control appliances and endpoints from the cloud server.
Request
POST /<target>/api/assetActionUpdate
Request Body
Property |
Type |
Description |
| action | <string> | Poll actions (e.g syncsynthetic, syncsuppress) |
| scope | <string> | Scope of update – (See Below) |
The scope defines which devices will have the action set. The options are:
-
-
- endpoints: All endpoint devices
- appliances” All appliances
- all: All devices – endpoints and appliances
-
Get Asset Action Update (/api/getAssetActionUpdate)
Description
Returns the last dataset from the specific asset (appliance or endpoint). The dataset is the data returned from the polling action. For example, if the polling action is GetLog, then the dataset will be the various logs associeted with the GetLog poll request. The action datasets are overwritten, that is, only the very last dataset is stored.
Request
POST /<target>/api/getAssetActionUpdate
Request Body
Property |
Type |
Description |
| machine_id | <string> | The machine ID to return the dataset for. |
POST Body Example
{
“machine_id”: “0e370bc63aa7”
}
Response
The response is a standard status object with the data being an object with the relevant dataset as described below.
Status Object:
Property |
Type |
Value |
| status | <string> | success or error |
| msg | <string> | Success or error message |
| data | <JSON object> | The JSON object conatinsing the returned asset data |
Where the returned JSON data object is defined as:
Property |
Type |
Description |
| machine_id | <string> | The machine ID for the dataset |
| cust_id | <string> | Customer ID |
| url | <string> | URL of the serving cloud server |
| ip_addr | <ip addr> | IP address of the originating appliance |
| type | <string> | Type of poll response |
| agentType | <string> | Type of device Endpoint or Appliance |
| pollData | <string> | The string containing the actual dataset information |
| date | <date> | Time and date the dataset was returned |
Example response:
{
“status”: “success”,
“data”: {
“custID”: “4a4052fa6a96”,
“machine_id”: “886f52fcaadd”,
“url”: “dev1.byte25.com”,
“ipAddr”: “172.16.19.247”,
“type”: “pollresponse”,
“agentType”: “appliance”,
“polldata”: “Response from webserver socket init”,
“date”: “2023-12-12 00:46:44”
}
}
Data Extraction API Calls
Description
Returns an array in JSON format for the top X values for a particular metric, customer and subnet for a specified timeframe. For example return the top 20 applications for a particular subnet for the last 7 days. Or the top talkers/IP addresses for a subnet for the lat 4 hours.
The getTopXData API is restricted to short term data – that is a maximum timeframe of 7 days of data may be returned.
Request
POST /<target>/api/getTopXData
Request Body
Property |
Type |
Description |
| field | <string> | Type specific metric to return. See below for available options. |
| source | <string> | Can be either subnet or flowsource specifying whether data returned should be for a specific subnet or flowsource |
| timerange | <object> | The time range for the query. See below for timerange object format. |
| value | <string> | The value for the subnet or flowsource for the query. Subnet values are the subnet address in CIDR format, for example 192.168.1.0/24, flowsource value is the IP address of the specific NetFlow source. |
The available field options include (but are not limited to):
- src_ip, the top talkers based on source address (client side of flow)
- dest_ip, the top talkers based on destination address (client side of flow)
- application, the top application (layer 7 apps from DPI collector)
- app_proto, the top service types (layer 4 apps from NetFlow collector)
- transport_type, for example multicast, unicast. Broadcast traffic
- proto, IP protocol
- dest_port, Layer 4 TCP/UDP port
timerange – Object Structure
Property |
Type |
Description |
| format | <string> | The format of the time range. Currently on daterel is available that is a relative data. For example last 24 hours, last 7 days |
| gte | <string> | The starting time for the query, expresses as now – <d | h >. For example” ‘now – 48h’ is the last 48 hours, ‘now – 7d’ is the last 7 days. |
| lte | <string> | The end time for the query. For example, ‘now’ |
POST Body Example
Description
Returns an array in JSON format for the bytes per second To and From for a particular customer and subnet for a specified timeframe.
The getTimeSeriesData API is restricted to short term data – that is a maximum timeframe of 7 days of data may be returned.
Request
POST /<target>/api/getTimeSeriesData
Request Body
Property |
Type |
Description |
| source | <string> | Can be either subnet or flowsource specifying whether data returned should be for a specific subnet or flowsource |
| timerange | <object> | The time range for the query. See below for timerange object format. |
| value | <string> | The value for the subnet or flowsource for the query. Subnet values are the subnet address in CIDR format, for example 192.168.1.0/24, flowsource value is the IP address of the specific NetFlow source. |
timerange – Object Structure
Property |
Type |
Description |
| format | <string> | The format of the time range. Currently on daterel is available that is a relative data. For example last 24 hours, last 7 days |
| gte | <string> | The starting time for the query, expresses as now – <d | h >. For example” ‘now – 48h’ is the last 48 hours, ‘now – 7d’ is the last 7 days. |
| lte | <string> | The end time for the query. For example, ‘now’ |
POST Body Example
{
“source”: “subnet”,
“timerange”: {
“format”: “daterel”,
“gte”: “now-7d”,
“lte”: “now”
},
“value”: “192.168.10.0/24”
}
Response
[
{
“x”: “Tue 16/12 16:00”,
“y”: 0,
“c”: “To (bps)”,
“epoch”: 1765861200000
},
{
“x”: “Tue 16/12 16:00”,
“y”: 0,
“c”: “From (bps)”,
“epoch”: 1765861200000
},
{
“x”: “Tue 16/12 17:00”,
“y”: 7725,
“c”: “To (bps)”,
“epoch”: 1765864800000
},
{
“x”: “Tue 16/12 17:00”,
“y”: 7725,
“c”: “From (bps)”,
“epoch”: 1765864800000
},
….
{
“x”: “Tue 23/12 16:00”,
“y”: 0,
“c”: “From (bps)”,
“epoch”: 1766466000000
}
]
SNMP
Set SNMP Device (/api/setSNMPDevice)
Description
Adds a new SNMP device to the customer SNMP configuration
Request
POST /<target>/api/setSNMPDevice
Request Body
Property |
Type |
Description |
| action | <string> | Currently only add is supported |
| deviceObj | <JSON Object> | An object specifying the polled device options (see below) |
deviceObj – Polled Device Object Structure
Property |
Type |
Description |
| appliance_id | <string> | ID of the appliance that will poll the device |
| appliance_ip | <ip_addr> | IP address of the appliance that will poll the device |
| cust_id | <string> | Customer_ID |
| description | <string> | Description of the polled device (taken from SNMP) |
| interval | <integer> | Polling interval in seconds |
| ip_addr | <ip_addr> | IP address device to be polled |
| label | <string> | User defined label for device being polled |
| monitored_ifs | <array> | Array of specific interfaces to be polled (see below) |
| snmp | <object> | Object defining the SNMP polling parameters (see below) |
monitored_ifs – Monitored Interfaces Array structure ( as part of Polled Device Object)
Property |
Type |
Description |
| if_index | <integer> | SNMP index of monitored interface |
| if_label | <string> | User defined label for interface being polled |
| if_metric_set | <string> | Metrics set to be polled (Refer to SNMP Architecture page) |
| if_name | <string> | Name of interface from SNMP |
| if_type | <string> | Type of interface (e.g Ethernet) |
| metrics | <array> | Array of SNMP oid:label pair objects to poll (See example below) |
snmp – SNMP Object structure ( as part of Polled Device Object)
Property |
Type |
Description |
| version | <string> | < snmpv1 | snmpv2 | snmpv3> |
| comm_string | <string> | SNMP community string (Version 1 & 2) |
| v3username | <string> | SNMP username (Version 3) |
| v3seclevel | <string> | Permissions allowed (Version 3) |
| v3authprotocol | <string> | Supported digest algorithm for SNMPv3 messages that require authentication: (Version 3) |
| v3authkey | <string> | Authentication Key (Version 3) |
| v3privprotocol | <string> | Supported encryption algorithm for SNMPv3 messages (Version 3) |
| v3privkey | <string> | Encryption Key (Version 3) |
POST Body Example
{
“action”: “add”,
“deviceObj”: {
“description”: “GS716Tv3 ProSafe 16-port Gigabit Ethernet Smart Switch, 6.3.1.43, B1.0.0.4”,
“cust_id”: “2a4052fa6a96”,
“ip_addr”: “172.16.19.245”,
“label”: “Office Switch”,
“poll_type”: “snmpv2c”,
“interval”: 300,
“appliance_id”: “886f52fcaadd”,
“appliance_ip”: “172.16.19.247”,
“monitored_infs”: [
{
“if_index”: “1”,
“if_name”: “1 Gigabit – Level”,
“if_type”: “Ethernet”,
“if_label”: “WOTSO Uplink”,
“if_metric_set”: “fullmetrics”,
“metrics”: [
{
“oid”: “1.3.6.1.2.1.2.2.1.10.1”,
“label”: “ifInOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.16.1”,
“label”: “ifOutOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.13.1”,
“label”: “ifInDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.19.1”,
“label”: “ifOutDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.14.1”,
“label”: “ifInErrors”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.20.1”,
“label”: “ifOutErrors”
}
]
},
{
“if_index”: “16”,
“if_name”: “16 Gigabit – Level”,
“if_type”: “Ethernet”,
“if_label”: “Mirror Port”,
“if_metric_set”: “fullmetrics”,
“metrics”: [
{
“oid”: “1.3.6.1.2.1.2.2.1.10.16”,
“label”: “ifInOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.16.16”,
“label”: “ifOutOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.13.16”,
“label”: “ifInDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.19.16”,
“label”: “ifOutDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.14.16”,
“label”: “ifInErrors”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.20.16”,
“label”: “ifOutErrors”
}
]
}
],
“snmp”: {
“version”: “snmpv2c”,
“comm_string”: “public”
}
}
}
Response
The response is a standard status object
Status Object:
Property |
Value |
| status | <string> success or error |
| msg | <string> Success or Error Message |
Get SNMP Device Info (/api/getSNMPDevice)
Description
Returns the current SNMP config from the customer associated with the logged in user. Slightly different information is returned dependent on the type parameter in the POST body:
Type config:
Reads the SNMP config and returns an SNMP Device Object (see above)
Type stats:
Reads the SNMP config and returns an SNMP Device Object (see above), also adds statistrics relating to the last 4 hours used for sparkline data.
Request
POST /<target>/api/getSNMPDevice
Request Body
Property |
Type |
Description |
| type | <string> | Type of data to return either stats or config |
POST Body Example
{
“type”: “stats”
}
Response
Status object:
Property |
Value |
| status | success or error |
| data | SNMP Config Object |
| msg | Success or error message |
Return data example (for type ‘stats’):
[
{
“description”: “KYOCERA Document Solutions Printing System”,
“cust_id”: “2a4052fa6a96”,
“ip_addr”: “172.16.19.53”,
“label”: “Printer”,
“poll_type”: “snmpv2c”,
“interval”: 300,
“appliance_id”: “886f52fcaadd”,
“appliance_ip”: “172.16.19.247”,
“monitored_infs”: [
{
“if_index”: “1”,
“if_name”: “eth0”,
“if_type”: “Ethernet”,
“if_label”: “Interface”,
“if_metric_set”: “fullmetrics”,
“metrics”: [
{
“oid”: “1.3.6.1.2.1.2.2.1.10.1”,
“label”: “ifInOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.16.1”,
“label”: “ifOutOctets”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.13.1”,
“label”: “ifInDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.19.1”,
“label”: “ifOutDiscards”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.14.1”,
“label”: “ifInErrors”
},
{
“oid”: “1.3.6.1.2.1.2.2.1.20.1”,
“label”: “ifOutErrors”
}
],
“metric_vals”: {
“ifOutOctet_Diff”: 261172,
“ifInOctet_Diff”: 1258424
}
}
],
“snmp”: {
“version”: “snmpv2c”,
“comm_string”: “public”
}
}
]
Get SNMP Volume Data (/api/getSNMPVolumeData)
Description
Returns SNMP volume data for all configured SNMP interfaces for the specified time frame in CSV format.
The CSV data is returned with the following columns:
-
-
- Date: Date string in the format DD-MM-YYYY HH:mm:SS
- HourID: Hour identifier in format HH
- MinID: Minute identifier in the format mm
- Device Name: Device name string
- Device IP: Device IP address
- Device Description: Device descritpion
- Interface Name: Interface name
- Interface Label: User defined interface label
- Interface Index: Interface index
- In Octets: Interface inbound bytes
- Out Octets: Interface outboud bytes
- In Discards: Interface inbound discarded frames
- Out Discards: Interface outbound discarded frames
- In Errors: Interface inbound errors
- Out Errors: Interface outbound errors
-
Request
POST /<target>/api/getSNMPVolumeData
Request Body
The POST body takes a time object that defines the time range for the API request. Note that the other report parameters, such as Customer is contained in the API key – this ensures data segregation/itegrity by restricting queries to different customer’s data.
The time range object sent in the POST body has three types (defined below):
- Relative Date (daterel) – Range relative to now. For example the last 7 days or now – 7 days
- Absolute (absolute) – Range based on time between two timestamps gte and lte expressed in epoch milliseconds
- Absolute Date String (absdatestr) – Range between two timestamps get and lte expressed as a date string in format yyyy-MM-dd HH:mm
Relative Data Time Property Object Format
Property |
Type |
Description |
| format | <string> | daterel – Relative time range |
| range | <string> | The time range unit – days or hours <d|h> |
| value | <integer> | The actual value for the time range |
Relative Date POST body example
{
“time”: {
“format”: “daterel”,
“range”: “d”,
“value”: 30
}
}
Absolute Property Object Format
Property |
Type |
Description |
| format | <string> | absolute – Relative time range |
| gte | <date> | Start date as epoch milliseconds |
| lte | <date> | End date as epoch milliseconds |
Absolute POST body example
{
“time”: {
“format”: “absolute”,
“gte”: 1754229600000,
“lte”: 1756908000000
}
}
Absolute Date String Time Property Object Format
Property |
Type |
Description |
|
format |
<string> |
absdatestr – Relative time range |
|
gte |
<date> |
Date string with format yyyy-MM-dd HH:mm |
|
lte |
<date> |
Date string with format yyyy-MM-dd HH:mm |
Absolute Date String POST body example
{
“time”: {
“format”: “absdatestr”,
“gte”: “2025-08-20 01:00”,
“lte”: “2025-09-04 05:00”
}
}