Skip to content

Allow an item

POST/settings/allowed-items

Endpoint API · Allowed Items

Exempt an item from conviction.

Required permissionendpoint-state:update

Parameters

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

Request body

Content type: application/json

Request body fields

typestringrequired
Property by which an item is allowed.
Must be one of: path, sha256, certificateSigner, posixPath.
propertiesobjectrequired
Allowed item properties.
Show child attributesHide child attributes
fileNamestring
File name.
pathstring
Path for the application.
sha256string
Sha256 value for the application.
certificateSignerstring
Value saved for the certificateSigner.
commentstringrequired
Comment indicating why the item should be allowed.
originPersonIdstring (uuid)
Person associated with the endpoint where the item to be allowed was last seen.
originEndpointIdstring (uuid)
Endpoint where the item to be allowed was last seen.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/allowed-items" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"type\": \"path\",
  \"properties\": {
    \"fileName\": \"filename.txt\",
    \"path\": \"\$desktop/documents/filename.txt\"
  },
  \"comment\": \"Item is not a Malware\",
  \"originPersonId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",
  \"originEndpointId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/allowed-items",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'type': 'path',
    'properties': {   'fileName': 'filename.txt',
                      'path': '$desktop/documents/filename.txt'},
    'comment': 'Item is not a Malware',
    'originPersonId': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'originEndpointId': '3fa85f64-5717-4562-b3fc-2c963f66afa6'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "type": "path",
  "properties": {
    "fileName": "filename.txt",
    "path": "$desktop/documents/filename.txt"
  },
  "comment": "Item is not a Malware",
  "originPersonId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "originEndpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/allowed-items" -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/settings/allowed-items", strings.NewReader(`{
  "type": "path",
  "properties": {
    "fileName": "filename.txt",
    "path": "$desktop/documents/filename.txt"
  },
  "comment": "Item is not a Malware",
  "originPersonId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "originEndpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}`))
    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/settings/allowed-items", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "type": "path",
  "properties": {
    "fileName": "filename.txt",
    "path": "$desktop/documents/filename.txt"
  },
  "comment": "Item is not a Malware",
  "originPersonId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "originEndpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Allowed item created.

Response fields

idstring (uuid)required
Unique ID for the allowed application.
createdAtstring (date-time)required
Date and time (UTC) when the allowed application was created.
updatedAtstring (date-time)
Date and time (UTC) when the allowed application was updated.
propertiesobjectrequired
Allowed item properties.
Show child attributesHide child attributes
fileNamestring
File name.
pathstring
Path for the application.
sha256string
Sha256 value for the application.
certificateSignerstring
Value saved for the certificateSigner.
commentstringrequired
Comment indicating why the item was allowed.
typestringrequired
Property by which an item is allowed.
Must be one of: path, sha256, certificateSigner, posixPath.
createdByobject
User.
Show child attributesHide child attributes
idstring (uuid)required
Unique ID for the user.
namestring
Person's name.
originPersonobject
User.
Show child attributesHide child attributes
idstring (uuid)required
Unique ID for the user.
namestring
Person's name.
originEndpointobject
Represents a referenced object.
Show child attributesHide child attributes
idstring (uuid)required
The ID of the referenced object.

Errors

Status Meaning
409 Item already exists.
500 Unexpected error.

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

Response examples

201

{
  "id": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2019-09-23T12:02:01.700Z",
  "updatedAt": "2019-09-23T12:02:01.700Z",
  "properties": {
    "fileName": "string",
    "path": "string",
    "sha256": "string",
    "certificateSigner": "string"
  },
  "comment": "string",
  "type": "path",
  "createdBy": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string"
  },
  "originPerson": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string"
  },
  "originEndpoint": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}

See the guide for a narrative walkthrough of this API.