Skip to content

Scan endpoints

POST/endpoints/scans

Endpoint API · Scans

Sends a request to multiple endpoints to perform or configure a scan.

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

idsarray of string (uuid)required
List of endpoints IDs.
Must contain 1–500 items.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/scans" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"ids\": [
    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",
    \"9d5d6819-0238-43e6-ba03-815cae0d474d\",
    \"2da8b591-9164-4f7e-a367-ad9b9cb77736\",
    \"66046f6a-bff0-4b51-aa0b-ac18bd363207\"
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/scans",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'ids': [   '3fa85f64-5717-4562-b3fc-2c963f66afa6',
               '9d5d6819-0238-43e6-ba03-815cae0d474d',
               '2da8b591-9164-4f7e-a367-ad9b9cb77736',
               '66046f6a-bff0-4b51-aa0b-ac18bd363207']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "9d5d6819-0238-43e6-ba03-815cae0d474d",
    "2da8b591-9164-4f7e-a367-ad9b9cb77736",
    "66046f6a-bff0-4b51-aa0b-ac18bd363207"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/scans" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/scans", strings.NewReader(`{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "9d5d6819-0238-43e6-ba03-815cae0d474d",
    "2da8b591-9164-4f7e-a367-ad9b9cb77736",
    "66046f6a-bff0-4b51-aa0b-ac18bd363207"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/scans", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "9d5d6819-0238-43e6-ba03-815cae0d474d",
    "2da8b591-9164-4f7e-a367-ad9b9cb77736",
    "66046f6a-bff0-4b51-aa0b-ac18bd363207"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

202 — Scan requests have been processed. Accepted requests are returned in items, and rejected requests are returned in errors.

Response fields

itemsarray of object
List of endpoint scan requests that were accepted.
Response to a previous request to scan an endpoint.
Show child attributesHide child attributes
idstring (uuid)required
The endpoint id.
statusstringrequired
Status of an endpoint action request.
Must be one of: requested.
requestedAtstring (date-time)required
Time when the scan was requested.
errorsarray of object
List of endpoint scan requests that could not be accepted.
Error details for an endpoint action request that could not be accepted for a specific endpoint.
Show child attributesHide child attributes
idstring (uuid)required
The endpoint id.
errorCodestringrequired
Machine-readable error code for an endpoint action request. The errorMessage field of the error response will contain a human-readable description of the error.
Must be one of: notFound, notSupported, conflict, permissionDenied, internalError.
endpointErrorCodestring
Optional code that maps to an error message.
errorMessagestringrequired
A human-readable error message describing the error in more detail.
Must be at most 250 characters long.

Errors

Status Meaning
400 Bad request.
404 None of the requested endpoints were found.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

202

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "requested",
      "requestedAt": "2026-07-28T00:00:00Z"
    }
  ],
  "errors": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "errorCode": "notFound",
      "endpointErrorCode": "string",
      "errorMessage": "string"
    }
  ]
}

See the guide for a narrative walkthrough of this API.