Get Investigations by ID

Overview

This endpoint retrieves the complete details for a single investigation case by its unique ID. By providing the investigations-id in the path, you can fetch a full snapshot of the case, including its attributes and relationships to other resources. You can also use the optional include parameter to efficiently pull in related data, like evidence, within the same API call. You should use this API whenever you need to fetch the current state and all associated details of a specific investigation.

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)

GET https://{Trellix EDR_gateway_URL}/edr/v2/investigations/{investigations-id}

Example — {investigations-id}: f61dd2a0-37e9-11ec-982e-000000000000

Request

Request headers

Authorization: Bearer <your_bearer_token>
Content-Type: application/vnd.api+json
x-api-key: <your_api_key>
Accept-Encoding: gzip

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.
Accept-Encoding: This is an optional header you can include to tell the server you can accept a compressed response (using gzip), which can make the data transfer faster.

Request parameters

Parameters	Data type/Values	Description

investigationId	string	Unique identifier for investigation case.
include	string	Specifies related resources to include in the response payload. Use this parameter to retrieve associated data in a single API call, reducing the need for subsequent requests. Example: When retrieving an investigation, including `evidence` will return both the investigation details and the related evidence data.
Accept-Encoding	string	Enable GZIP Compression to return compressed data. Example: gzip, deflate, br

Response

Response example

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "totalResourceCount": 1
  },
  "data": {
    "type": "investigations",
    "id": "0dc44100-430f-11ee-8b79-000000000000",
    "attributes": {
      "created": "2023-08-25T06:17:22.960Z",
      "lastModified": "2023-08-25T06:17:22.960Z",
      "name": "MVISION_API_EDR_BVT_00_2023-08-25T10:45:09.966333",
      "owner": "unknown",
      "summary": "",
      "source": "unknown",
      "isAutomatic": true,
      "hint": "MVISION_API_EDR_vaii00_{{date}}{{int}}",
      "caseType": "Malware",
      "investigated": true,
      "status": "In progress",
      "priority": "Unspecified"
    },
    "relationships": {
      "evidenceInfo": {
        "data": [
          {
            "evidenceType": "device",
            "evidenceValue": {
              "attributes": {
                "name": "MVISION_API_EDR_BVT_IP_0008",
                "hostName": "Vais9999-vm",
                "rawData": "",
                "__clue": "true",
                "__fromThreat": ""
              },
              "created": "2023-08-25T06:17:23.055Z"
            }
          }
        ],
        "links": {
          "self": "/edr/v2/investigations/0dc44100-430f-11ee-8b79-000000000000/evidence?page[offset]=0&page[limit]=100",
          "first": "/edr/v2/investigations/0dc44100-430f-11ee-8b79-000000000000/evidence?page[offset]=0&page[limit]=100",
          "prev": "/edr/v2/investigations/0dc44100-430f-11ee-8b79-000000000000/evidence?page[offset]=0&page[limit]=100",
          "next": "/edr/v2/investigations/0dc44100-430f-11ee-8b79-000000000000/evidence?page[offset]=0&page[limit]=100",
          "last": "/edr/v2/investigations/0dc44100-430f-11ee-8b79-000000000000/evidence?page[offset]=0&page[limit]=100"
        }
      }
    }
  }
}

Response codes

Status	Response	Description
200	OK	Your request was processed successfully. The server has returned the requested data.
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 `(Content-Type)` is not supported.
429	Too Many Requests	You've exceeded the rate limit by sending too many requests in a short period. The `Retry-After` header in the response will tell you how long to wait before trying again.
500	Internal Server Error	Something went wrong on the server's end. This is not an issue with your request.