Retrieve File

post /public_api/v1/endpoints/file_retrieval

Retrieve files from selected endpoints. You can retrieve up to 20 files, from no more than 10 endpoints.

Response is concatenated using AND condition (OR is not supported).
Offset is the zero-based number of incidents from the start of the result set.

Required license: Cortex XDR Prevent or Cortex XDR Pro per Endpoint

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

Accept-Encoding String

For retrieving a compressed gzipped response

Example: acceptEncoding_example

Default: gzip

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
          -H
          'Accept-Encoding: acceptEncoding_example'
      
      'https://api-yourfqdn/public_api/v1/endpoints/file_retrieval'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}"

headers = {
    'Authorization': "SOME_STRING_VALUE",
    'x-xdr-auth-id': "SOME_STRING_VALUE",
    'Accept-Encoding': "SOME_STRING_VALUE",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/endpoints/file_retrieval", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/v1/endpoints/file_retrieval")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["Accept-Encoding"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "request_data": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": [
          "string"
        ]
      }
    ],
    "files": {
      "windows": [
        "string"
      ],
      "linux": [
        "string"
      ],
      "macos": [
        "string"
      ]
    },
    "incident_id": "string"
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/v1/endpoints/file_retrieval");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("Accept-Encoding", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/endpoints/file_retrieval")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("Accept-Encoding", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "Accept-Encoding": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "filters": [
      [
        "field": "endpoint_id_list",
        "operator": "in",
        "value": ["string"]
      ]
    ],
    "files": [
      "windows": ["string"],
      "linux": ["string"],
      "macos": ["string"]
    ],
    "incident_id": "string"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/endpoints/file_retrieval")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/v1/endpoints/file_retrieval",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}",
  CURLOPT_HTTPHEADER => [
    "Accept-Encoding: SOME_STRING_VALUE",
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/v1/endpoints/file_retrieval");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "Accept-Encoding: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/endpoints/file_retrieval");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("Accept-Encoding", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"files\":{\"windows\":[\"string\"],\"linux\":[\"string\"],\"macos\":[\"string\"]},\"incident_id\":\"string\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataobjectrequired

A dictionary containing the API request fields.

filtersarray

An array of filter fields.

[

fieldstring (Enum)

Identifies the field the filter must match:

endpoint_id_list

Allowed values:"endpoint_id_list"

operatorstring (Enum)

Identifies the comparison operator you want to use for this filter. Valid keywords and values are: in

'endpoint_id_list'

Allowed values:"in"

valuearray[string]

Value that this filter must match. Valid keywords:

'endpoint_id_list': List of strings.

]

filesobject

One of the operating system types must be included.

windowsarray[string]

linuxarray[string]

macosarray[string]

incident_idstring

Incident ID. When included in the request, the Retrieve File action will appear in the Cortex XDR Incident View Timeline tab.

REQUEST
{
  "request_data": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": [
          "example"
        ]
      }
    ],
    "files": {
      "windows": [
        "example"
      ],
      "linux": [
        "example"
      ],
      "macos": [
        "example"
      ]
    },
    "incident_id": "example"
  }
}

Responses

Body

application/json

replyobject

JSON object containing the query result.

action_idstring

ID of action to retrieve files from selected endpoints. Response only indicates the request was successfully sent to the endpoint. To track if the file was retrieved successfully either: in the Cortex XDR console, navigate to Response > Action Center > Isolation and search for the action ID. Make sure the Action ID field is selected in the table Layout settings by selecting the three vertical dots. To view the file, send a File Retrieval Details request.

statusstring

endpoints_countstring

Number of endpoints included in the request.

RESPONSE
{
  "reply": {
    "action_id": "example",
    "status": "example",
    "endpoints_count": "example"
  }
}

Bad Request. Got an invalid JSON.

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Unauthorized access. User does not have the required license type to run this API.

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Internal server error. A unified status for API communication type errors.