The Lumu Defender API uses HTTP requests and returns JSON responses. This documentation outlines the required endpoints, request parameters, sample JSON payloads, and expected response messages.
The Defender API is language-agnostic and supports both incoming and outgoing data. All API calls are secured with HTTPS (SSL/TLS) and authenticated using API keys.
The Defender API requires each client to use a unique API key, referred to in this documentation as
{company-key}
. This key is available in the Integrations section of the Lumu Portal and is managed directly by your organization's administrators.
The ability to integrate Lumu with your security stack via the Defender API is included in the Lumu Defender subscription. This tier enables seamless integration of Lumu’s real-time analysis into your existing security tools, helping you mitigate and remediate compromise incidents quickly and accurately.
Choose the method that best fits your organization’s needs and environment.
The following resources are accessible via the Lumu Defender API. These are familiar terms that can be traced to their counterpart in the Lumu Portal.
Resource
|
Description
|
administration |
Used to retrieve data on users and labels.
|
incidents |
Used to subscribe to incident updates, retrieve incident data, and manage incident statuses.
|
adversarial-activity |
Used to retrieve all adversarial activity detected across your network perimeter.
|
spambox |
Used to retrieve adversarial activity associated with your organization’s email intelligence.
|
All API endpoints are relative to the base URL. For example, since the base URL is URL of
https://defender.lumu.io/api
, the /incidents endpoint would be https://defender.lumu.io/api/incidents
Paging results can be controlled using query string parameters. This feature is available for endpoints that return more data than can fit in a single response.
Query Params
|
Data Type
|
Description
|
page |
integer (optional)
|
Page number of the result set (default: 1).
|
items |
integer (optional)
|
Limit the number of results per page (default: 50, max: 100)
|
https://defender.lumu.io/api/administration/labels?key={company-key}&items=20&page=3
Paginated queries deliver pagination info at the end of each query, for example:
"prev"
or "next"
may not be returned if there is no previous or next page; "total"
may appear in some specific services, such as for the administration endpoint.
The Defender API uses a standardized date and time format to ensure consistency and interoperability with third-party applications. All date and time values are returned in Coordinated Universal Time (UTC) and follow the formats defined by RFC 3339 and ISO 8601 (YYYY-MM-DDTHH:mm:ss:sssZ
). For example,
2021-03-21T18:25:43.000Z
, where the trailing Z
indicates that the time zone is UTC (GMT).
You can submit queries to the Defender API using date and time values in your local time zone. However, note that the API will automatically convert all time zone values to UTC.
"2025-02-23T15:15:30.234Z"
When using the
fromDate
and
ToDate
parameters in your queries, ensure that the specified date range does not exceed 31 calendar days and is not older than 180 calendar days from the current date.
The following example will return error 400 as it includes a time range greater than 31 days:
hours
parameter are limited to a maximum of 767 hours (approximately 30 days) prior to the current date and time. The following example shows a query where the hours value exceeds this limit, which will result in a 400 Bad Request error.The Lumu API uses standard HTTP features and standard HTTP status codes to indicate errors.
HTTP Code
|
Description
|
200 |
OK Everything worked as expected. The expected data was returned. |
400 |
Bad Request Client-side error status. Verify malformed request syntax, invalid request message parameters, etc. |
401 |
Unauthorized The provided API key is not valid. |
403 |
Forbidden Your company does not have sufficient privileges to access the API resource. |
500 |
Internal server error Our application server encountered a problem, try again later and if the problem persist, please let us know. |
For queries that return listed results, you can specify the maximum number of items to be returned using the following query string parameter:
Query Params
|
Data Type
|
Description
|
max-items |
Integer (optional) |
The maximum number of items to be returned (default: 10, max: 10240).
|
https://defender.lumu.io/resources/administration/labels?key={company-key}&items=20&page=3&max-items=50
The
/administration
endpoints contain information about labels and users of the company. Labels help identify and classify compromise distribution across your infrastructure.
Get a paginated list of all the labels created for the company and its details such as id, name and business relevance. The items are sorted by the label id in ascending order.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Parameter
|
Description
|
relevance |
Business relevance. Companies define label relevance according to their business reality for faster data-supported decisions. The possible values are 1 (low), 2 (medium) and 3 (high).
|
Get details such as id, name and business relevance from a specific label.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Get a paginated list of all the users registered in the company and their details. The items are sorted by the user id in ascending order.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Parameter
|
Description
|
deactivated |
User account status. The two possible values are false(user is active) and true(user is deactivated). A deactivated account cannot login in to the Lumu Portal.
|
Get specific user details such as id, name, and role.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
The
/incidents
endpoints contain information about incidents of the company. Lumu groups all occurrences of contacts to malicious infrastructure by an adversary and presents them consolidated in the form of incidents.
Incident statuses and types may vary over time. Therefore, any implementation using endpoints that accept these as query parameters should account for possible changes.
The following are the current values for these parameters:
"open", "muted", "closed"
.
"C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
Lumu-User-Id
header in the request, using the user's ID as its value.
Lumu-User-Id:2
. This parameter is optional. If it is not included, the action will not be associated with any specific user. For example, if the query header includes the ID 2, which corresponds to the user "Integration user", the incident log will appear as shown in the following image.
Retrieves a paginated list of incidents for the company, ordered by most recent first.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Body parameters
Name
|
Data Type
|
Description
|
fromDate |
date-time (optional)
|
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
|
toDate |
date-time (optional)
|
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
|
status |
array (optional)
|
Incident status. If not specified, all objects are returned. Example: "open", "muted", "closed"
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3, 5
|
Retrieves detailed information about a specific incident. The response may include additional parameters—such as DNSPacketExtraInfo—depending on the data collection source.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Retrieves contextual information related to a specific incident.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
hash-type |
Message-digest algorithm (Cryptographic Hash Function) you are requesting, can correspond to SHA256, SHA1 or MD5. If a hash type isn't requested, this will return a SHA256 hash by default. This parameter isn't case sensitive.
|
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Name
|
Data Type
|
Description
|
comment |
string
|
comment to be added to the incident
|
Retrieves a paginated list of open incidents for the company, ordered by most recent first.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal. |
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name |
Data Type
|
Description
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,
|
Retrieves a paginated list of muted incidents for the company, ordered by most recent first.
Query Params
|
Description
|
key |
Your company unique API key available at the Lumu Portal.
|
pages |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,
|
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Name
|
Data Type
|
Description
|
comment |
string (optional)
|
Comment to be added in the Incident log. Example: "Internal penetration tests"
|
Enable notifications for a specific incident.
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Name
|
Data Type
|
Description
|
comment |
string (optional)
|
Comment to be added in the Incident log. Example: "Internal penetration tests"
|
Query Params
|
Description
|
key |
Your company's unique API key, available in the Lumu Portal.
|
Name
|
Data Type
|
Description
|
comment |
string (optional)
|
Comment to be added in the Incident log. Example: "Internal penetration tests"
|
Lumu provides a streaming endpoint to subscribe to real-time updates on activity notifications. Establishing a connection to the streaming API means making a very long-lived HTTP request, and parsing the response incrementally.
The following endpoint can be used to stream notifications to any client that implements WebSockets.
wss://defender.lumu.io/api/incidents/subscribe?key={company-key}
See the following examples of notification logs received by a WebSocket client from the Defender API:
The stream notification log for a new incident detection will be similar to the following:
In the following log, we have an example of an incident that was marked as read:
In the following log, we have an example of an incident that was marked as closed:
In the following log, we have an example of an incident that was marked as muted:
In the following log, we have an example of an incident that was marked as unmuted:
An incident is updated whenever new contact with an Indicator of Compromise (IoC) is detected. The following log shows an example of an updated incident:
The
/adversarial-activity
endpoints contain detailed compromise activity detected on your network, categorized according to threat type.
Get a paginated summary of the adversaries contacted by endpoints within a time-frame
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
fromDate |
date-time (optional)
|
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
|
toDate |
date-time (optional)
|
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
|
endpoints |
array (optional)
|
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Retrieves a paginated list of details about adversarial hosts contacted within the specified number of past hours.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
max-items |
(only for GET) Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
endpoints |
array (optional)
|
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a list of adversarial hosts contacted within a number of past hours in plain text format.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
endpoints |
array (optional)
|
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a paginated summary of the incidents across endpoints within a time-frame.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
fromDate |
date-time (optional)
|
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
|
toDate |
date-time (optional)
|
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
|
adversaries |
array (optional)
|
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a paginated list of endpoints and adversarial contacts within a number of past hours.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
The maximum number of items that will be returned (default: 10, max: 10240)
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
endpoints |
array (optional)
|
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a list of endpoints with adversarial contacts within a number of hours in plain text format.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
max-items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
adversaries |
array (optional)
|
List of adversarial hosts. If not specified, all objects are returned. Example: "phishing-site.domain".
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
endpoint-identification-type |
string (optional)
|
Type of endpoint identification. Possible values: "IP" (IP address), "ID" (case-sensitive endpoint ID) - The default value is "ID".
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a paginated summary of the adversaries related to Lumu Email Intelligence that were contacted by endpoints.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
fromDate |
date-time (optional)
|
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
|
toDate |
date-time (optional)
|
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a detailed list of adversarial hosts contacted, related to Lumu Email Intelligence, within a number of past hours.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
Name
|
Data Type
|
Description
|
hours |
date-time (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
labels |
array (optional)
|
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
|
Get a list of adversarial hosts contacted within a number of past hours in plain text format.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
max-items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
Get a paginated summary of the adversaries related to Lumu Email Intelligence.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
fromDate |
date-time (optional)
|
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
|
toDate |
date-time (optional)
|
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
Get a detailed list of adversarial hosts related to Lumu Email Intelligence, within a number of past hours.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
page |
Page number of the result set (default: 1)
|
items |
Limit the number of results per page (default: 50, max: 100)
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|
adversary-types |
array (optional)
|
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
|
Get a list of adversarial hosts contacted within a number of past hours in plain text format.
Query Params |
Description
|
key |
Your company's unique API key, available in the Lumu Portal
|
hours |
(only for GET) The number of past hours you want to narrow your results to (default: 1)
|
max-items |
Limit the number of results per page (default: 50, max: 100)
|
Name
|
Data Type
|
Description
|
hours |
integer (optional)
|
The number of past hours you want to narrow your results to. The default value 1.
|