Overview
This endpoint creates a new investigation case. By providing initial details like a case name, priority, and a key piece of evidence (such as an IP address or endpoint name), you can trigger the platform's automated data collection and analysis workflows. The API responds immediately with the full object of the newly created investigation, including its unique ID and current status.
You should use this API to programmatically trigger an investigation from an external tool like a Security Information and Event Management (SIEM) or a Security Orchestration, Automation, and Response (SOAR) platform. It's the primary method for automating the first step of an incident response workflow, allowing you to automatically create a case based on an alert from another system.
Authentication
Authentication type: Bearer Token, API Key.
You can create a token using client credentials obtained through the developer portal. The API Key (x-api-key) is provided in your onboarding email or on the API Access Management page.
Path (or URL)
POST https://{Trellix EDR_gateway_URL}/edr/v2/investigations
You can get the gateway URL from the Trellixon-boarding email. For example, https://api.manage.trellix.com
Request
Request headers
Authorization: Bearer <your_bearer_token> Content-Type: application/vnd.api+json x-api-key: <your_api_key>
Authorization: This header is used to authenticate your request. You need to replace
<your_bearer_token>with the actual token you generate.Content-Type: This header tells the server that the request body format is
json:api. Even though this specific call has no request body, the API requires this header.x-api-key: This is a custom header required by the Trellix API for authentication. You'll need to replace
<your_api_key>with the key from your onboarding email or the API Access Management page.
Request body
Example 1:
{
"data": {
"type": "investigations",
"attributes": {
"caseType": "Malware",
"caseName": "Test Incident Name",
"caseHint": "hostname",
"casePriority": "High",
"evidenceType": "IP",
"address": "123.123.123.123"
}
}
}Example 2:
{
"data": {
"type": "investigations",
"attributes": {
"eventSrc": "TrellixESM",
"caseType": "Malware",
"caseName": "Trellix API - EDR Investigations Demo 10 August 2020 - 4",
"caseHint": "hostname4-10-08-2020",
"casePriority": "Low",
"evidenceType": "Device",
"name": "es",
"hostName": "EMB-0BXXXE9-P08_20161003101947"
}
}
Request parameters
There are no request parameters.
Response
Response example
{
"data": {
"id": "9e576c20-c526-11ea-abc6-000000000001",
"type": "investigations",
"attributes": {
"name": "Test Incident Name",
"summary": "Test Incident Summary",
"created": "2020-07-13T16:33:44.418Z",
"owner": "testuser@email.com",
"source": "unknown",
"isAutomatic": true,
"hint": "hostname",
"caseType": "malware",
"lastModified": "2020-07-13T16:33:44.418Z",
"investigated": true,
"status": "In progress",
"priority": "high"
}
}
}Response codes
Status | Response | Description |
|---|---|---|
201 | Created | Your request was successful, and a new resource was created as a result. Your request was successful, and a new resource was created. The response includes details such as the resource ID, which you can use to track or manage the resource. |
400 | Bad request | The server couldn't understand your request, likely due to a syntax error or an invalid parameter. |
401 | Access denied request | Your request was rejected because it lacks valid authentication credentials. Check your API key and token. |
403 | Forbidden | You are not authorized to access this resource. While your credentials may be valid, you don't have the necessary permissions. |
404 | Not Found | The specific resource or endpoint you requested does not exist. |
415 | Unsupported Media Type | The server rejected your request because the data format |
429 | Too Many Requests | You've exceeded the rate limit by sending too many requests in a short period. The |
500 | Internal Server Error | Something went wrong on the server's end. This is not an issue with your request. |