openapi: 3.0.0 info: description: This is the OAS 3.0 specification for the Endpoint API in Sophos Central. version: 1.72.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' title: Endpoint API tags: - name: Adaptive Attack Protection description: Adaptive Attack Protection. - name: Allowed Items description: Manage allowed items. These are always treated as non-malicious. - name: Blocked Addresses description: Manage blocked IP addresses for a customer. - name: Blocked Items description: >- Manage blocked items. These are always treated as malicious or potentially malicious. - name: Device Software description: Manage device software. - name: Diagnose description: Run diagnostics on an endpoint. - name: Downloads description: Endpoint Installer Download APIs. - name: Endpoint Groups Management description: Manage endpoint groups in the directory. - name: Endpoint Isolation description: Manage endpoint isolation. - name: Endpoint Tags description: Assign tags to endpoints. - name: Endpoints description: >- Search for endpoints, view individual endpoint details, delete an endpoint or restore endpoints. - name: Event Journal description: Event journal settings for a customer's computers and servers. - name: Exploit Mitigation description: Manage Exploit Mitigation settings. - name: Forensic Logs description: Collect forensic logs from an endpoint. - name: Global Tamper Protection description: View global Tamper Protection settings. - name: Health Status description: Manage endpoint health status. - name: Intrusion Prevention description: Manage Intrusion Prevention exclusions and related settings. - name: Isolation Exclusions description: Manage isolation exclusions. - name: Maintenance description: Endpoint Maintenance Mode related APIs. - name: Memory Dump description: Generate and collect memory dump from an endpoint. - name: Migrations description: Migrate endpoints from one tenant to another. - name: Packages description: Manage endpoint software packages. - name: Peripheral Control description: Manage Peripheral Control settings. - name: Policy Management description: Endpoint Policy Management APIs. - name: Scanning Exclusions description: >- Manage files, processes and applications excluded from different types of scans. - name: Scans description: Scan an endpoint. - name: Tamper Protection description: Turn Tamper Protection on or off on an endpoint and view settings. - name: Update Checks description: Check for Sophos software updates on an endpoint. - name: Web Control description: Manage Web Control settings. servers: - url: 'https://api-{dataRegion}.central.sophos.com/endpoint/v1' description: Regional service in the production environment. variables: dataRegion: description: Data region where tenant data is stored. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /downloads: get: x-soph-permissions: 'endpoint-state:update' tags: - Downloads summary: Download installers description: Get all the endpoint installer links for a tenant. operationId: listInstallersByTenantId parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: requestedProducts description: >- Products to include in the installers. All values are given if you don't use filters. style: form explode: false required: false schema: type: array items: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna - in: query name: platforms description: >- Specify which platforms to include. All values are given if you don't use filters. style: form explode: false required: false schema: type: array items: type: string description: OS platform type. enum: - windows - linux - macOS responses: '200': description: Endpoint installers. content: application/json: schema: type: object required: - tenant - licensedProducts - installers description: Lists the installers that can be downloaded. properties: tenant: type: object required: - id description: Tenant. properties: id: description: Tenant ID. type: string format: uuid licensedProducts: type: array description: Products that the tenant is licensed to install. items: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna installers: type: array description: List of installers. items: type: object required: - platform - type - supportedProducts - downloadUrl description: Installer. properties: productName: description: Product name. type: string platform: type: string description: OS platform type. enum: - windows - linux - macOS type: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm supportedProducts: type: array description: Products to install. items: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna downloadUrl: description: Download URL. type: string format: uri example: productName: Sophos Endpoint Protection platform: windows type: computer supportedProducts: - endpointProtection - interceptX downloadUrl: >- https://api.sophos.com/api/download/.../SophosSetup.exe '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /endpoints: get: x-soph-permissions: 'endpoint-state:read' tags: - Endpoints summary: Query endpoints description: Get all the endpoints for the specified tenant. operationId: listEndpointsByTenantId parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' - in: query name: healthStatus description: Find endpoints by health status. style: form explode: false required: false schema: type: array items: type: string enum: - bad - good - suspicious - unknown - in: query name: type description: >- Find endpoints by type. Please note that the type `securityVm` is no longer used. style: form explode: false required: false schema: type: array items: type: string enum: - computer - server - securityVm - in: query name: tamperProtectionEnabled description: Find endpoints by whether Tamper Protection is turned on. required: false schema: type: boolean - in: query name: tamperProtectionSupported description: Find endpoints by whether Tamper Protection is supported. required: false schema: type: boolean - in: query name: lockdownStatus description: >- Find endpoints by lockdown status. Please note that the following statuses are no longer used: `creatingWhitelist`, `installing`, `registering`, and `starting` are now reported as `locking`; `stopping` is reported as `locked`; and `uninstalled` is reported as `unlocked`. style: form explode: false required: false schema: type: array items: type: string enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - in: query name: overallEncryptionStatus description: Find endpoints by overall encryption status. style: form explode: false required: false schema: type: array items: type: string enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - notAvailable - unmanaged - in: query name: lastSeenBefore description: >- Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive). examples: FullUtcTimestamp: value: '2019-09-23T12:02:01.700Z' DateOnly: value: '2019-09-23' Duration: value: '-P3DT4H5M0S' summary: >- 3 days 4 hours 5 minutes and 0 seconds ago, value is case-sensitive DaysOnly: value: P1D summary: one day from now HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: PT200S summary: 200 seconds from now required: false schema: type: string - in: query name: lastSeenAfter description: >- Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). examples: FullUtcTimestamp: value: '2019-09-23T12:02:01.700Z' DateOnly: value: '2019-09-23' Duration: value: PT4H500S summary: '4 hours and 500 seconds from now, value is case-sensitive' DaysOnly: value: '-P1D' summary: one day ago HoursOnly: value: PT2H summary: 2 hours from now MinutesOnly: value: PT20M summary: 20 minutes from now SecondsOnly: value: '-PT200S' summary: 200 seconds ago required: false schema: type: string - in: query name: lastOsUpdateBefore description: >- Find endpoints that last applied an operating system update before the given date and time (UTC) or a duration relative to the current date and time (exclusive). examples: FullUtcTimestamp: value: '2025-02-23T12:02:01.700Z' DateOnly: value: '2025-03-23' Duration: value: '-P3DT4H5M0S' summary: >- 3 days 4 hours 5 minutes and 0 seconds ago. Value is case-sensitive DaysOnly: value: '-P1D' summary: one day ago HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: '-PT200S' summary: 200 seconds ago required: false schema: type: string - in: query name: lastOsUpdateAfter description: >- Find endpoints that last applied an operating system update after the given date and time (UTC) or a duration relative to the current date and time (inclusive). examples: FullUtcTimestamp: value: '2025-02-23T12:02:01.700Z' DateOnly: value: '2025-02-23' Duration: value: PT4H500S summary: 4 hours and 500 seconds from now. Value is case-sensitive DaysOnly: value: '-P1D' summary: one day ago HoursOnly: value: PT2H summary: 2 hours from now MinutesOnly: value: PT20M summary: 20 minutes from now SecondsOnly: value: '-PT200S' summary: 200 seconds ago required: false schema: type: string - in: query name: ids description: Find endpoints with the specified IDs. style: form explode: false required: false schema: type: array items: type: string - in: query name: isolationStatus description: Find endpoints by isolation status. required: false schema: type: string enum: - isolated - notIsolated - in: query name: hostnameContains description: Find endpoints where the hostname contains the given string. required: false schema: type: string - in: query name: serialNumberContains description: Find endpoints where the serial number contains the given string. required: false schema: type: string - in: query name: associatedPersonContains description: >- Find endpoints where the name of the person associated with the endpoint contains the specified string. required: false schema: type: string - in: query name: groupNameContains description: >- Find endpoints where the name of the group the endpoint is in contains the given string. required: false schema: type: string - in: query name: search description: Term to search for in the specified search fields. required: false schema: type: string - in: query name: searchFields description: >- List of search fields for finding the search term you enter. Defaults to all applicable fields. style: form explode: false required: false schema: type: array items: type: string enum: - hostname - groupName - associatedPersonName - ipAddresses - osName - serialNumber - tags - in: query name: ipAddresses description: Find endpoints by IP addresses. style: form explode: false required: false schema: type: array items: type: string - in: query name: online description: Find endpoints currently online. required: false schema: type: boolean - in: query name: cloud description: Find endpoints that are cloud instances. You must use URL encoding. examples: DifferentProvider: value: 'azure:42349c92,aws:i-3bc4829309' AllInstancesForProvider: value: aws AllInstanceForAWSAndSpecificInstanceForAzure: value: 'aws,azure:4975692a' InstancesWithAnyProvider: value: 'i-3bc4829309,42349c92' style: form explode: false required: false schema: type: array items: type: string pattern: >- ^(aws|azure|gcp)|((aws|azure|gcp):([0-9a-zA-Z-_]{1,64}))|([0-9a-zA-Z-_]{1,64})$ - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: view description: >- Type of view to be returned in the response. The 'basic' view contains only ID, type, tenant and hostname fields. A 'summary' view includes the most commonly used set of fields, broadly comparable to the default columns in the Central UI, and 'full' returns all fields available. If no view is specified the default 'summary' view will be returned. required: false schema: type: string enum: - basic - summary - full - in: query name: assignedToGroup description: Whether endpoint is assigned to a group. required: false schema: type: boolean - in: query name: groupIds description: Match endpoints by assigned group. required: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: macAddresses description: >- Find endpoints by MAC Addresses. Can be in EUI-48 or EUI-64 format, case insensitive, colon, hyphen or dot separated, or with no separator e.g. 01:23:45:67:89:AB, 01-23-45-67-89-ab, 0123.4567.89ab, 0123456789ab, 01:23:45:67:89:ab:cd:ef. style: form explode: false required: false schema: type: array items: type: string pattern: '^([0-9a-fA-F:\-\.]){10,32}$' - in: query name: includeTags description: >- Finds endpoints with the specified tags. The tags are listed as comma separated key:value pairs. required: false schema: type: array maxItems: 5 items: type: string description: A tag key or tag display string. pattern: '^[^:]{1,40}(:[^:]{0,40})?$' - in: query name: excludeTags description: >- Finds endpoints without the specified tags. The tags are listed as comma separated key:value pairs. required: false schema: type: array maxItems: 5 items: type: string description: A tag key or tag display string. pattern: '^[^:]{1,40}(:[^:]{0,40})?$' - in: query name: hasTags description: >- If not set, finds endpoints that have no tags. If set, finds endpoints that have one or more tags assigned. required: false schema: type: boolean - in: query name: lastAgentUpdateBefore description: >- Finds endpoints where the agent was last updated before a specified UTC date and time, or before a date relative to the current date and time. examples: Between15DaysAnd30Days: value: '-P15D' Over30Days: value: '-P30D' CustomOver45Hours: value: '-PT45H' FullUtcTimestamp: value: '2024-10-13T12:02:01.700Z' DateOnly: value: '2024-10-13' required: false schema: type: string - in: query name: lastAgentUpdateAfter description: >- Finds endpoints where the agent was last updated after a specified UTC date and time, or after a date relative to the current date and time. examples: Within15Days: value: '-P15D' Between15DaysAnd30Days: value: '-P30D' CustomWithin45Hours: value: '-PT45H' FullUtcTimestamp: value: '2025-10-13T12:02:01.700Z' DateOnly: value: '2019-10-13' required: false schema: type: string responses: '200': description: >- Page of endpoints. Example shows response with the 'view' parameter set to 'full'. content: application/json: schema: type: object required: - items - pages properties: items: type: array description: List of endpoints. items: type: object required: - id - type - hostname - os properties: id: description: Unique ID for the endpoint. type: string format: uuid type: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. hostname: description: Hostname of the endpoint. type: string health: type: object description: Health status of an endpoint. required: - overall - threats - services properties: overall: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown threats: type: object description: Threats on the endpoint. required: - status properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown services: type: object description: Status of services on the endpoint. required: - status - serviceDetails properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown serviceDetails: description: Details of services on the endpoint. type: array items: type: object required: - name - status properties: name: description: Service name. type: string status: type: string description: Status of a service on an endpoint. enum: - running - stopped - missing os: type: object description: OS information. required: - platform - name properties: isServer: description: Whether the OS is a server OS. type: boolean platform: type: string description: OS platform type. enum: - windows - linux - macOS name: description: OS name as reported by the endpoint. type: string majorVersion: description: OS major version. type: integer minorVersion: description: OS minor version. type: integer build: description: OS build. type: integer ipv4Addresses: description: List of IPv4 addresses. type: array items: type: string ipv6Addresses: description: List of IPv6 addresses. type: array items: type: string macAddresses: description: List of MAC addresses. type: array items: type: string group: type: object description: Endpoint group. properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid groupHierarchy: description: >- List of groups in the hierarchy, starting with the group the endpoint is in and ending with the top-level group. type: array items: type: object description: A single group in the endpoint group hierarchy. required: - name - id properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid parentId: description: >- Unique ID of the parent group. Omitted for the top-level group. type: string format: uuid example: name: Group B id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 example: - name: Data Team id: 7ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - name: Backend Team id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 - name: Engineering id: 550e8400-e29b-41d4-a716-446655440000 associatedPerson: type: object description: Person associated with an endpoint. properties: name: description: Person's name. type: string viaLogin: description: Person's login on the endpoint. type: string id: description: Unique ID for the Person. type: string format: uuid tamperProtectionSupported: description: Whether the endpoint supports Tamper Protection. type: boolean tamperProtectionEnabled: description: Whether Tamper Protection is turned on. type: boolean assignedProducts: description: Products assigned to the endpoint. type: array items: type: object required: - code - version properties: code: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna version: description: Version of a product assigned to an endpoint. type: string status: type: string description: >- Installation status of a product assigned to the endpoint. enum: - installed - notInstalled packages: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string deviceSoftware: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string lastSeenAt: description: >- Date and time (UTC) when the endpoint last communicated with Sophos Central. example: '2019-09-23T12:02:01.700Z' type: string lastOsUpdateAt: description: >- Date and time (UTC) when the endpoint last applied an operating system update. example: '2025-02-23T12:02:01.700Z' type: string serialNumber: description: >- The hardware/BIOS serial number of the endpoint. Only Mac endpoints report their serial number currently. example: P28DA81LMD5T type: string encryption: type: object description: Endpoint encryption state. required: - volumes properties: volumes: description: Endpoint volumes. type: array items: type: object description: Endpoint volume encryption status. required: - volumeId - status properties: volumeId: description: Endpoint volume ID. type: string status: type: string description: Endpoint volume encryption status. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - unknown overallStatus: type: string description: The overall encryption status of the endpoint. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - notAvailable - unmanaged lockdown: type: object description: Server Lockdown status. required: - status properties: status: type: string description: >- Server lockdown status. Please note that the following statuses are no longer used: `creatingWhitelist`, `installing`, `registering`, and `starting` are now reported as `locking`; `stopping` is reported as `locked`; and `uninstalled` is reported as `unlocked`. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking tags: description: List of tags. type: array maxItems: 15 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. online: description: Whether endpoint is currently online. type: boolean cloud: type: object description: Endpoint cloud. required: - provider - instanceId properties: provider: type: string description: Cloud provider in which the endpoint is running. enum: - aws - azure instanceId: description: Unique ID for the cloud instance. type: string pattern: '^([0-9a-zA-Z-_]{1,64})' isolation: type: object description: Endpoint isolation state as reported by an endpoint. required: - status properties: status: type: string description: Isolation status reported by endpoint. enum: - isolated - notIsolated adminIsolated: description: Whether isolation was triggered by an admin. type: boolean selfIsolated: description: >- Whether isolation was triggered by the endpoint itself. type: boolean cloned: description: >- Whether the endpoint has been cloned by another endpoint. type: boolean lastAgentUpdateAt: description: >- Date and time (UTC) when the agent was last successfully updated. example: '2019-09-23T12:02:01.700Z' type: string pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: >- (Optional) The total number of items on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /endpoints/delete: post: x-soph-permissions: 'endpoint-computer:delete OR endpoint-server:delete' tags: - Endpoints summary: Delete endpoints description: Delete a list of endpoints. operationId: deleteEndpoints parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Request to delete multiple endpoints. required: - endpointIds properties: endpointIds: description: Endpoint IDs to delete. type: array uniqueItems: true minItems: 1 maxItems: 1000 items: type: string format: uuid example: endpointIds: - fcf47d9f-7ba6-4ac9-bda2-1d4f6de49c0f - 3d8ecdb5-37bf-4f26-b47b-1b185781ff9b responses: '200': description: Deleted endpoint IDs. content: application/json: schema: type: object description: Response to a request to delete endpoints. required: - endpointIds properties: endpointIds: description: Endpoint IDs that have been queued for deletion. type: array uniqueItems: true items: type: string format: uuid '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Endpoints summary: Get endpoint details description: Get an endpoint based on ID. operationId: getEndpointById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: view description: >- Type of view to be returned in the response. The 'basic' view contains only ID, type, tenant and hostname fields. A 'summary' view includes the most commonly used set of fields, broadly comparable to the default columns in the Central UI, and 'full' returns all fields available. If no view is specified the default 'summary' view will be returned. required: false schema: type: string enum: - basic - summary - full responses: '200': description: >- Existing endpoint. Example shows response with the 'view' parameter set to 'full'. content: application/json: schema: type: object required: - id - type - hostname - os properties: id: description: Unique ID for the endpoint. type: string format: uuid type: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. hostname: description: Hostname of the endpoint. type: string health: type: object description: Health status of an endpoint. required: - overall - threats - services properties: overall: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown threats: type: object description: Threats on the endpoint. required: - status properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown services: type: object description: Status of services on the endpoint. required: - status - serviceDetails properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown serviceDetails: description: Details of services on the endpoint. type: array items: type: object required: - name - status properties: name: description: Service name. type: string status: type: string description: Status of a service on an endpoint. enum: - running - stopped - missing os: type: object description: OS information. required: - platform - name properties: isServer: description: Whether the OS is a server OS. type: boolean platform: type: string description: OS platform type. enum: - windows - linux - macOS name: description: OS name as reported by the endpoint. type: string majorVersion: description: OS major version. type: integer minorVersion: description: OS minor version. type: integer build: description: OS build. type: integer ipv4Addresses: description: List of IPv4 addresses. type: array items: type: string ipv6Addresses: description: List of IPv6 addresses. type: array items: type: string macAddresses: description: List of MAC addresses. type: array items: type: string group: type: object description: Endpoint group. properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid groupHierarchy: description: >- List of groups in the hierarchy, starting with the group the endpoint is in and ending with the top-level group. type: array items: type: object description: A single group in the endpoint group hierarchy. required: - name - id properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid parentId: description: >- Unique ID of the parent group. Omitted for the top-level group. type: string format: uuid example: name: Group B id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 example: - name: Data Team id: 7ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - name: Backend Team id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 - name: Engineering id: 550e8400-e29b-41d4-a716-446655440000 associatedPerson: type: object description: Person associated with an endpoint. properties: name: description: Person's name. type: string viaLogin: description: Person's login on the endpoint. type: string id: description: Unique ID for the Person. type: string format: uuid tamperProtectionSupported: description: Whether the endpoint supports Tamper Protection. type: boolean tamperProtectionEnabled: description: Whether Tamper Protection is turned on. type: boolean assignedProducts: description: Products assigned to the endpoint. type: array items: type: object required: - code - version properties: code: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna version: description: Version of a product assigned to an endpoint. type: string status: type: string description: >- Installation status of a product assigned to the endpoint. enum: - installed - notInstalled packages: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string deviceSoftware: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: The name of the available device software. type: string lastSeenAt: description: >- Date and time (UTC) when the endpoint last communicated with Sophos Central. example: '2019-09-23T12:02:01.700Z' type: string lastOsUpdateAt: description: >- Date and time (UTC) when the endpoint last applied an operating system update. example: '2025-02-23T12:02:01.700Z' type: string serialNumber: description: >- The hardware/BIOS serial number of the endpoint. Only Mac endpoints report their serial number currently. example: P28DA81LMD5T type: string encryption: type: object description: Endpoint encryption state. required: - volumes properties: volumes: description: Endpoint volumes. type: array items: type: object description: Endpoint volume encryption status. required: - volumeId - status properties: volumeId: description: Endpoint volume ID. type: string status: type: string description: Endpoint volume encryption status. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - unknown overallStatus: type: string description: The overall encryption status of the endpoint. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - notAvailable - unmanaged lockdown: type: object description: Server Lockdown status. required: - status properties: status: type: string description: >- Server lockdown status. Please note that the following statuses are no longer used: `creatingWhitelist`, `installing`, `registering`, and `starting` are now reported as `locking`; `stopping` is reported as `locked`; and `uninstalled` is reported as `unlocked`. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking tags: description: List of tags. type: array maxItems: 15 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. online: description: Whether endpoint is currently online. type: boolean cloud: type: object description: Endpoint cloud. required: - provider - instanceId properties: provider: type: string description: Cloud provider in which the endpoint is running. enum: - aws - azure instanceId: description: Unique ID for the cloud instance. type: string pattern: '^([0-9a-zA-Z-_]{1,64})' isolation: type: object description: Endpoint isolation state as reported by an endpoint. required: - status properties: status: type: string description: Isolation status reported by endpoint. enum: - isolated - notIsolated adminIsolated: description: Whether isolation was triggered by an admin. type: boolean selfIsolated: description: >- Whether isolation was triggered by the endpoint itself. type: boolean cloned: description: Whether the endpoint has been cloned by another endpoint. type: boolean lastAgentUpdateAt: description: >- Date and time (UTC) when the agent was last successfully updated. example: '2019-09-23T12:02:01.700Z' type: string '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:delete' tags: - Endpoints summary: Delete endpoint description: Deletes a specified endpoint. operationId: deleteEndpointById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid responses: '200': description: Endpoint deleted. content: application/json: schema: type: object description: Response to a previous request to delete a specific endpoint. properties: deleted: description: Whether the endpoint was deleted. type: boolean '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/adaptive-attack-protection': get: x-soph-permissions: 'endpoint-state:read' tags: - Adaptive Attack Protection summary: Get AAP settings description: Get Adaptive Attack Protection settings for an endpoint. operationId: getEndpointAAP parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid responses: '200': description: Adaptive Attack Protection settings retrieved successfully. content: application/json: schema: type: object description: Adaptive Attack Protection response object. properties: desiredState: type: object description: Desired status for Adaptive Attack Protection. properties: enabled: description: >- Whether Adaptive Attack Protection is turned on for the endpoint. type: boolean source: description: >- Whether the change was made automatically by the endpoint or manually by a user in Sophos Central. type: string enum: - user - automatic expiresAfter: description: >- Duration (in ISO 8601 format) after which the endpoint will leave Adaptive Attack Protection. Only present if a user requested the change. type: string maxLength: 6 example: enabled: true expiresAfter: P7D source: user actualState: type: object description: Status of Adaptive Attack Protection. properties: enabled: description: >- Whether Adaptive Attack Protection is turned on for the endpoint. type: boolean lastUpdatedAt: description: >- When Adaptive Attack Protection status was last updated. type: string format: date-time expiresAt: description: When Adaptive Attack Protection will be turned off. type: string format: date-time example: enabled: true lastUpdatedAt: '2023-11-21T12:55:11.123Z' expiresAt: '2023-11-28T12:55:11.123Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Adaptive Attack Protection summary: Update AAP settings description: Update Adaptive Attack Protection settings for an endpoint. operationId: updateEndpointAAP parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: >- Request to update Adaptive Attack Protection settings for an endpoint. properties: enabled: description: Whether the endpoint will enter Adaptive Attack Protection. type: boolean expiresAfter: description: >- Duration (in ISO 8601 format) after which the endpoint will leave Adaptive Attack Protection. type: string maxLength: 6 examples: EnableEndpointAAP: value: enabled: true expiresAfter: P7D UpdateEndpointAAPExpiryTime: value: expiresAfter: P1D DisableEndpointAAP: value: enabled: false responses: '200': description: Adaptive Attack Protection settings updated successfully. content: application/json: schema: type: object description: Adaptive Attack Protection response object. properties: desiredState: type: object description: Desired status for Adaptive Attack Protection. properties: enabled: description: >- Whether Adaptive Attack Protection is turned on for the endpoint. type: boolean source: description: >- Whether the change was made automatically by the endpoint or manually by a user in Sophos Central. type: string enum: - user - automatic expiresAfter: description: >- Duration (in ISO 8601 format) after which the endpoint will leave Adaptive Attack Protection. Only present if a user requested the change. type: string maxLength: 6 example: enabled: true expiresAfter: P7D source: user actualState: type: object description: Status of Adaptive Attack Protection. properties: enabled: description: >- Whether Adaptive Attack Protection is turned on for the endpoint. type: boolean lastUpdatedAt: description: >- When Adaptive Attack Protection status was last updated. type: string format: date-time expiresAt: description: When Adaptive Attack Protection will be turned off. type: string format: date-time example: enabled: true lastUpdatedAt: '2023-11-21T12:55:11.123Z' expiresAt: '2023-11-28T12:55:11.123Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/tamper-protection': get: x-soph-permissions: 'endpoint-state:read' tags: - Tamper Protection summary: Get settings description: Get Tamper Protection settings for a specified endpoint. operationId: getEndpointTamperProtectionSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid responses: '200': description: Tamper Protection settings for an endpoint. content: application/json: schema: type: object description: >- Response to a previous request to update Tamper Protection settings. required: - enabled - password properties: enabled: type: boolean description: >- Whether Tamper Protection should be turned on for the endpoint. password: type: string description: Current Tamper Protection password. previousPasswords: type: array description: Old Tamper Protection passwords. items: type: object required: - password - invalidatedAt properties: password: type: string description: The old Tamper Protection password. invalidatedAt: type: string description: >- Time when the old Tamper Protection password was changed. format: date-time '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Tamper Protection summary: Update settings description: >- Turns Tamper Protection on or off on an endpoint. Or generates a new Tamper Protection password. Note that Tamper Protection can be turned on for an endpoint only if it has also been turned on globally. operationId: updateEndpointTamperProtectionSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: description: Sends a request to update Tamper Protection settings. required: true content: application/json: schema: type: object description: Request to change Tamper Protection settings for the endpoint. properties: enabled: description: >- Whether Tamper Protection should be turned on for the endpoint. type: boolean regeneratePassword: description: >- Whether a new Tamper Protection password should be generated. type: boolean examples: TamperProtectionEnable: value: enabled: true TamperProtectionDisable: value: enabled: false TamperProtectionRegeneratePassword: value: regeneratePassword: true TamperProtectionEnableAndRegeneratePassword: value: enabled: true regeneratePassword: true responses: '201': description: Tamper Protection settings for an endpoint. content: application/json: schema: type: object description: >- Response to a previous request to update Tamper Protection settings. required: - enabled - password properties: enabled: type: boolean description: >- Whether Tamper Protection should be turned on for the endpoint. password: type: string description: Current Tamper Protection password. previousPasswords: type: array description: Old Tamper Protection passwords. items: type: object required: - password - invalidatedAt properties: password: type: string description: The old Tamper Protection password. invalidatedAt: type: string description: >- Time when the old Tamper Protection password was changed. format: date-time '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/scans': post: x-soph-permissions: 'endpoint-state:update' tags: - Scans summary: Scan an endpoint description: >- Sends a request to the specified endpoint to perform or configure a scan. operationId: requestEndpointScan parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: description: Endpoint scan request. required: true content: application/json: schema: type: object description: Request to configure or perform a scan on the endpoint. properties: {} examples: EndpointScanRequest: value: {} responses: '201': description: Endpoint scan request sent to the endpoint. content: application/json: schema: type: object description: Response to a previous request to scan an endpoint. required: - id - status - requestedAt properties: id: description: The endpoint id. type: string format: uuid status: type: string description: Status of an endpoint action request. enum: - requested requestedAt: description: Time when the scan was requested. type: string format: date-time '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/update-checks': post: x-soph-permissions: 'endpoint-state:update' tags: - Update Checks summary: Check for updates description: >- Sends a request to the endpoint to check for Sophos management agent software updates. operationId: requestEndpointUpdateCheck parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: description: Endpoint update check request. required: true content: application/json: schema: type: object description: >- Request to the endpoint to check for updates to the Sophos agent software and protection data. properties: {} examples: EndpointUpdateCheckRequest: value: {} responses: '201': description: Update check request sent to the endpoint. content: application/json: schema: type: object description: >- Response to a previous request to perform an update check on the endpoint. required: - id - status - requestedAt properties: id: description: The endpoint id. type: string format: uuid status: type: string description: Status of an endpoint action request. enum: - requested requestedAt: description: Time when the endpoint update check was requested. type: string format: date-time '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/forensic-logs': post: x-soph-permissions: 'endpoint-diagnose:create' tags: - Forensic Logs summary: Collect forensic log description: Sends a request to the endpoint to collect forensic log. operationId: collectEndpointForensicLog parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: description: Forensic log request. required: true content: application/json: schema: type: object description: Request to collect forensic log from the endpoint. required: - mode - expires properties: mode: type: string description: >- Supported forensic log collection modes. * `fast` - Collects a reduced set of diagnostic files. * `full` - Collects the full set of diagnostic files. * `standard` - The default mode. * `none` - Only collects the additional files specified in the request. This is intended for use when normal data has already been collected and some additional files are required. enum: - fast - full - standard - none expires: description: >- Maximum duration (in ISO 8601 format) for which the action is valid. This must be no less than 5 minutes and no more than 7 days. We recommend a duration of minutes or hours only. Express the duration only in terms of days, hours, minutes, and seconds (not in weeks or milliseconds). type: string password: description: >- Password to use to encrypt the file to upload. Blank if the archive file is not password protected. The supported encryption is AES-256 ZIP. type: string paths: description: List of additional file paths to include. type: array items: type: string maxItems: 50 examples: EndpointForensicLogRequest: value: mode: fast expires: PT4H responses: '202': description: Request accepted. content: application/json: schema: type: object description: >- Response to a previous request to collect forensic log from the endpoint. required: - id - status - receivedAt - expiresAt properties: id: description: >- Identifies a request to collect forensic log from the endpoint. type: string format: uuid status: type: string description: Status of an endpoint file collection. enum: - pending - finished - expired - failed receivedAt: description: Timestamp at which the action was received. type: string format: date-time expiresAt: description: Timestamp from when to ignore the action on the endpoint. type: string format: date-time errorMessage: description: Why the action failed. type: string forensicLogFile: type: object description: Details of the file uploaded by an endpoint. required: - fileName - sha256 - size properties: fileName: description: Name of the file. type: string sha256: description: SHA-256 hash of the file. type: string size: description: Size of the file in bytes. type: integer format: int64 examples: InProgressEndpointForensicLogResponse: value: id: f1f1f848-e969-4df2-b41f-31544e34ef31 status: pending receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/forensic-logs/{forensicLogRequestId}': get: x-soph-permissions: 'endpoint-diagnose:read' tags: - Forensic Logs summary: Get status description: Gets the status of the forensic log collection. operationId: getEndpointForensicLogStatus parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid - name: forensicLogRequestId in: path description: ID of the forensic log collection request. required: true schema: type: string format: uuid responses: '200': description: Forensic log collection status. content: application/json: schema: type: object description: >- Response to a previous request to collect forensic log from the endpoint. required: - id - status - receivedAt - expiresAt properties: id: description: >- Identifies a request to collect forensic log from the endpoint. type: string format: uuid status: type: string description: Status of an endpoint file collection. enum: - pending - finished - expired - failed receivedAt: description: Timestamp at which the action was received. type: string format: date-time expiresAt: description: Timestamp from when to ignore the action on the endpoint. type: string format: date-time errorMessage: description: Why the action failed. type: string forensicLogFile: type: object description: Details of the file uploaded by an endpoint. required: - fileName - sha256 - size properties: fileName: description: Name of the file. type: string sha256: description: SHA-256 hash of the file. type: string size: description: Size of the file in bytes. type: integer format: int64 examples: CompletedEndpointForensicLogResponse: value: id: fda552f8-a411-4663-b11b-4aa8284c77ef status: finished receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' forensicLogFile: fileName: >- forensic_sdu_b7e5f3aa-a7c6-43c6-a65e-3cd52008464b_62f01fb7-3dcb-40a7-9bab-1af32d5203e9.zip sha256: >- 99ff984dd6738eb99f2feaff54d0e93a8e820d8e3d817541960f7a88be628409 size: 12345 FailedEndpointForensicLogResponse: value: id: f1f1f848-e969-4df2-b41f-31544e34ef31 status: failed receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' errorMessage: The endpoint doesn't have a supported OS '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint or forensic log request for the provided ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/memory-dumps': post: x-soph-permissions: 'endpoint-diagnose:create' tags: - Memory Dump summary: Generate memory dump description: >- Instructs the target device to generate a memory dump of the specified process or the kernel. The dump is then uploaded to a customer-specified Amazon S3 bucket. operationId: collectEndpointMemoryDump parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: description: Memory dump request. required: true content: application/json: schema: type: object description: Request to generate and collect memory dump from the endpoint. required: - mode - expires properties: mode: type: string description: Supported memory dump modes. enum: - process - kernel pid: description: >- Process ID of the process for which a memory dump is required. If mode is 'process', then either PID or image name is required. This parameter is ignored for kernel memory dumps. type: integer format: int32 minimum: 0 imageName: description: >- The image name of the process for which a memory dump is required. If mode is 'process', then either PID or image name is required. This parameter is ignored for kernel memory dumps or if PID is supplied. type: string expires: description: >- Maximum duration (in ISO 8601 format) for which the action is valid. This must be no less than 5 minutes and no more than 7 days. We recommend a duration of minutes or hours only. Express the duration only in terms of days, hours, minutes, and seconds (not in weeks or milliseconds). type: string password: description: >- Password to use to encrypt the file to upload. Blank if the archive file is not password protected. The supported encryption is AES-256 ZIP. type: string examples: EndpointMemoryDumpRequest: value: mode: process pid: 1234 expires: PT4H responses: '202': description: Request accepted. content: application/json: schema: type: object description: >- Response to a previous request to generate and collect memory dump from the endpoint. required: - id - status - receivedAt - expiresAt properties: id: description: >- Identifies a request to generate and collect memory dump from the endpoint. type: string format: uuid status: type: string description: Status of an endpoint file collection. enum: - pending - finished - expired - failed receivedAt: description: Timestamp at which the action was received. type: string format: date-time expiresAt: description: Timestamp from when to ignore the action on the endpoint. type: string format: date-time errorMessage: description: Why the action failed. type: string memoryDumpFile: type: object description: Details of the file uploaded by an endpoint. required: - fileName - sha256 - size properties: fileName: description: Name of the file. type: string sha256: description: SHA-256 hash of the file. type: string size: description: Size of the file in bytes. type: integer format: int64 examples: InProgressEndpointMemoryDumpResponse: value: id: f1f1f848-e969-4df2-b41f-31544e34ef31 status: pending receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/memory-dumps/{memoryDumpRequestId}': get: x-soph-permissions: 'endpoint-diagnose:read' tags: - Memory Dump summary: Get status description: Gets the status of the memory dump collection. operationId: getEndpointMemoryDumpStatus parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid - name: memoryDumpRequestId in: path description: ID of the memory dump request. required: true schema: type: string format: uuid responses: '200': description: Memory dump collection status. content: application/json: schema: type: object description: >- Response to a previous request to generate and collect memory dump from the endpoint. required: - id - status - receivedAt - expiresAt properties: id: description: >- Identifies a request to generate and collect memory dump from the endpoint. type: string format: uuid status: type: string description: Status of an endpoint file collection. enum: - pending - finished - expired - failed receivedAt: description: Timestamp at which the action was received. type: string format: date-time expiresAt: description: Timestamp from when to ignore the action on the endpoint. type: string format: date-time errorMessage: description: Why the action failed. type: string memoryDumpFile: type: object description: Details of the file uploaded by an endpoint. required: - fileName - sha256 - size properties: fileName: description: Name of the file. type: string sha256: description: SHA-256 hash of the file. type: string size: description: Size of the file in bytes. type: integer format: int64 examples: CompletedEndpointMemoryDumpResponse: value: id: fda552f8-a411-4663-b11b-4aa8284c77ef status: finished receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' memoryDumpFile: fileName: >- memory_dump_b7e5f3aa-a7c6-43c6-a65e-3cd52008464b_62f01fb7-3dcb-40a7-9bab-1af32d5203e9.zip sha256: >- 99ff984dd6738eb99f2feaff54d0e93a8e820d8e3d817541960f7a88be628409 size: 12345 FailedEndpointMemoryDumpResponse: value: id: f1f1f848-e969-4df2-b41f-31544e34ef31 status: failed receivedAt: '2021-01-30T08:30:00.000Z' expiresAt: '2021-02-04T08:30:00.000Z' errorMessage: The endpoint doesn't have a supported OS '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint or memory dump request for the provided ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/allowed-items: get: x-soph-permissions: 'endpoint-state:read' tags: - Allowed Items summary: Get allowed items description: Get all allowed items. operationId: getAllowedItems parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: List of allowed items. content: application/json: schema: type: object description: Page of allowed items. required: - items - pages properties: items: type: array description: Allowed items. items: type: object required: - id - createdAt - comment - type - properties properties: id: description: Unique ID for the allowed application. type: string format: uuid createdAt: description: >- Date and time (UTC) when the allowed application was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: >- Date and time (UTC) when the allowed application was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Allowed item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was allowed. type: string type: type: string description: Property by which an item is allowed. enum: - path - sha256 - certificateSigner - posixPath createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Allowed Items summary: Allow an item description: Exempt an item from conviction. operationId: postAllowedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: New allowed item request. content: application/json: schema: type: object description: Request to allow an item. This exempts the item from conviction. required: - type - properties - comment properties: type: type: string description: Property by which an item is allowed. enum: - path - sha256 - certificateSigner - posixPath properties: type: object description: Allowed item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item should be allowed. type: string originPersonId: description: >- Person associated with the endpoint where the item to be allowed was last seen. type: string format: uuid originEndpointId: description: Endpoint where the item to be allowed was last seen. type: string format: uuid example: 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 responses: '201': description: Allowed item created. content: application/json: schema: type: object required: - id - createdAt - comment - type - properties properties: id: description: Unique ID for the allowed application. type: string format: uuid createdAt: description: >- Date and time (UTC) when the allowed application was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: >- Date and time (UTC) when the allowed application was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Allowed item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was allowed. type: string type: type: string description: Property by which an item is allowed. enum: - path - sha256 - certificateSigner - posixPath createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '409': description: Item already exists. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/allowed-items/{allowedItemId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Allowed Items summary: Get an allowed item description: Get an allowed item by ID. operationId: getAllowedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: allowedItemId in: path description: Allowed item ID. required: true schema: type: string format: uuid responses: '200': description: Allowed item. content: application/json: schema: type: object required: - id - createdAt - comment - type - properties properties: id: description: Unique ID for the allowed application. type: string format: uuid createdAt: description: >- Date and time (UTC) when the allowed application was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: >- Date and time (UTC) when the allowed application was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Allowed item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was allowed. type: string type: type: string description: Property by which an item is allowed. enum: - path - sha256 - certificateSigner - posixPath createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find allowed item. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Allowed Items summary: Update allowed item description: Update an allowed item. operationId: patchAllowedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: allowedItemId in: path description: Allowed item ID. required: true schema: type: string format: uuid requestBody: required: true description: Patch object to update the allowed item. content: application/json: schema: type: object description: >- Change an allowed item. Blocked items cannot be modified at this point. properties: comment: description: Comment indicating why the item should be allowed. type: string example: comment: Allow the patch request for Updating. responses: '200': description: Updated allowed item. content: application/json: schema: type: object required: - id - createdAt - comment - type - properties properties: id: description: Unique ID for the allowed application. type: string format: uuid createdAt: description: >- Date and time (UTC) when the allowed application was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: >- Date and time (UTC) when the allowed application was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Allowed item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was allowed. type: string type: type: string description: Property by which an item is allowed. enum: - path - sha256 - certificateSigner - posixPath createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '404': description: Can't find allowed item. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Allowed Items summary: Delete allowed item description: Deletes the specified allowed item. operationId: deleteAllowedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: allowedItemId in: path description: Allowed item ID. required: true schema: type: string format: uuid responses: '200': description: Can't find allowed item or it has been successfully deleted. content: application/json: schema: type: object description: Response to a request to delete a specific allowed item. properties: deleted: type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/blocked-addresses: get: x-soph-permissions: 'blocked-ips:read' tags: - Blocked Addresses summary: Get blocked addresses description: >- Get the list of all currently blocked IP addresses and IP address ranges. operationId: getBlockedAddressSets parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: sort description: >- Sort criteria for blocked communications. Valid sort fields are `item`, `createdAt` and `blockedUntil `. You can append ':asc' or ':desc' to one of the listed fields to specify the sort direction. The default sort is `createdAt:desc`. style: form required: false schema: type: string pattern: >- (^(item|createdAt|blockedUntil)$)|(^(item|createdAt|blockedUntil):(asc|desc)$) default: 'createdAt:desc' responses: '200': description: The list of currently blocked IP addresses and IP address ranges. content: application/json: schema: type: object description: Page of blocked IP addresses and IP ranges. required: - items - pages properties: items: type: array description: Blocked IP addresses and ranges. items: type: object description: A blocked IP address or IP range. properties: id: type: string format: uuid description: >- The identifier of the blocked IP address or IP range record. item: type: string description: >- A single IP address or an IP range. The IP can be IPv4 or IPv6 and the range can be specified using a dash or in CIDR format. comment: type: string description: >- Comment indicating why the IP address or IP range should be blocked. maxLength: 250 createdAt: type: string format: date-time description: >- When the IP address or IP range was set to be blocked. blockedUntil: type: string description: >- The time until which the IP address or IP range will be blocked, in ISO-8601 format. format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find customer. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/blocked-addresses/bulk: post: x-soph-permissions: 'blocked-ips:write' tags: - Blocked Addresses summary: Block multiple items description: >- Allows the user to specify multiple IP addresses or IP address ranges that devices should refuse to communicate with. This feature is only available on Windows devices. operationId: postBlockedAddressSets parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Request which specifies new IP addresses or ranges to block. content: application/json: schema: type: object description: Request to block multiple IP addresses and IP ranges. required: - items properties: items: type: array items: type: object description: Request to block a single IP address or IP address range. required: - item properties: item: type: string description: >- A single IP address or an IP address range. The IP can be IPv4 or IPv6 and the range can be specified using a dash or in CIDR format. example: - 1.1.2.3 - 1.2.2.3/17 - 1.3.2.3-1.3.2.6 - '2001:db8:3333:4444:5555:6666:7777:8888' - '2001:4860:4860::8888/32' - >- 2001:db8:3333:4444:5555:6666:7777:8888-2001:db8:3333:4444:5555:6666:7777:9999 comment: description: >- Comment indicating why the IP address or IP address range should be blocked. type: string maxLength: 250 expireInDays: description: >- Duration (in days) for which the IP address or IP address range should be blocked. Any decimal values are rounded down to an integer. type: integer format: int64 minimum: 1 maximum: 365 maxItems: 100 responses: '201': description: Newly blocked IP addresses or IP address ranges. content: application/json: schema: type: object description: A list of blocked IP addresses and IP ranges. properties: items: type: array items: type: object description: A blocked IP address or IP range. properties: id: type: string format: uuid description: >- The identifier of the blocked IP address or IP range record. item: type: string description: >- A single IP address or an IP range. The IP can be IPv4 or IPv6 and the range can be specified using a dash or in CIDR format. comment: type: string description: >- Comment indicating why the IP address or IP range should be blocked. maxLength: 250 createdAt: type: string format: date-time description: >- When the IP address or IP range was set to be blocked. blockedUntil: type: string description: >- The time until which the IP address or IP range will be blocked, in ISO-8601 format. format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find customer. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/blocked-addresses/bulk/delete: post: x-soph-permissions: 'blocked-ips:write' tags: - Blocked Addresses summary: Unblock items description: Remove multiple IP addresses or IP address ranges from being blocked. operationId: deleteBlockedAddressSets parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: >- Request which specifies which IP addresses and IP address ranges to unblock. content: application/json: schema: type: object description: IDs of the IP addresses and IP ranges to unblock. required: - ids properties: ids: type: array description: >- List of IDs for the records of IP addresses and ranges to unblock. items: type: string format: uuid responses: '200': description: >- The list of IDs for IP addresses or IP address ranges that failed to be unblocked. content: application/json: schema: type: object description: >- Response to a request to delete multiple blocked IP addresses or IP ranges. Specifies an array of identifiers for the IP records that couldn't be deleted. required: - failedToDelete properties: failedToDelete: type: array items: type: string format: uuid '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Unauthorized. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find customer. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/blocked-items: get: x-soph-permissions: 'endpoint-state:read' tags: - Blocked Items summary: Get blocked items description: Get all blocked items. operationId: getBlockedItems parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: List of blocked items. content: application/json: schema: type: object description: Page of blocked items. required: - items - pages properties: items: type: array description: Blocked items. items: type: object required: - id - createdAt - comment - type - properties properties: id: description: Blocked item ID. type: string format: uuid createdAt: description: >- Date and time (UTC) when the blocked item was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: >- Date and time (UTC) when the blocked item was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Blocked item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was blocked. type: string type: type: string description: Property by which an item is blocked. enum: - sha256 createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Blocked Items summary: Block an item description: Block an item from exoneration. operationId: postBlockedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: New blocked item request. content: application/json: schema: type: object description: >- Request to block an item. This exempts the item from exoneration. Items can only be blocked by their SHA256 checksums at this time. required: - type - properties - comment properties: type: type: string description: Property by which an item is blocked. enum: - sha256 properties: type: object description: Blocked item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item should be blocked. type: string example: type: sha256 properties: fileName: filename.txt path: $desktop/documents/filename.txt sha256: >- ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad comment: Item is a Malware responses: '201': description: Blocked item created. content: application/json: schema: type: object required: - id - createdAt - comment - type - properties properties: id: description: Blocked item ID. type: string format: uuid createdAt: description: Date and time (UTC) when the blocked item was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: Date and time (UTC) when the blocked item was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Blocked item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was blocked. type: string type: type: string description: Property by which an item is blocked. enum: - sha256 createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/blocked-items/{blockedItemId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Blocked Items summary: Get a blocked item description: Get a blocked item by ID. operationId: getBlockedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: blockedItemId in: path description: Blocked item ID. required: true schema: type: string format: uuid responses: '200': description: Blocked item. content: application/json: schema: type: object required: - id - createdAt - comment - type - properties properties: id: description: Blocked item ID. type: string format: uuid createdAt: description: Date and time (UTC) when the blocked item was created. example: '2019-09-23T12:02:01.700Z' type: string format: date-time updatedAt: description: Date and time (UTC) when the blocked item was updated. example: '2019-09-23T12:02:01.700Z' type: string format: date-time properties: type: object description: Blocked item properties. properties: fileName: description: File name. type: string path: description: Path for the application. type: string sha256: description: Sha256 value for the application. type: string certificateSigner: description: Value saved for the certificateSigner. type: string comment: description: Comment indicating why the item was blocked. type: string type: type: string description: Property by which an item is blocked. enum: - sha256 createdBy: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originPerson: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string originEndpoint: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '404': description: Can't find blocked item. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Blocked Items summary: Delete blocked item description: Deletes the specified blocked item. operationId: deleteBlockedItemById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: blockedItemId in: path description: Blocked item ID. required: true schema: type: string format: uuid responses: '200': description: Can't find blocked item or it has been successfully deleted. content: application/json: schema: type: object description: Response to a request to delete a specific blocked item. properties: deleted: type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/device-software: patch: x-soph-permissions: 'endpoint-server:update OR endpoint-computer:update' tags: - Device Software summary: Manage device software description: Update assigned endpoint device software in bulk. operationId: patchEndpointDeviceSoftwareBulk parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Computer and server definitions for assigned device software. properties: computer: type: object description: Request to change assigned device software for the endpoint. allOf: - type: object description: >- Input fields for a manage software request, excluding endpoint IDs. properties: protectionAssignedId: description: Protection device software. type: string example: MDR encryptionAssignedId: description: Encryption device software. type: string example: All ztnaAssignedId: description: ZTNA device software. type: string example: None - type: object required: - ids properties: ids: description: >- IDs for the endpoints getting device software updated. type: array maxItems: 1000 minItems: 1 items: type: string format: uuid description: Endpoint ID. server: type: object description: Request to change assigned device software for the endpoint. allOf: - type: object description: >- Input fields for a manage software request, excluding endpoint IDs. properties: protectionAssignedId: description: Protection device software. type: string example: MDR encryptionAssignedId: description: Encryption device software. type: string example: All ztnaAssignedId: description: ZTNA device software. type: string example: None - type: object required: - ids properties: ids: description: >- IDs for the endpoints getting device software updated. type: array maxItems: 1000 minItems: 1 items: type: string format: uuid description: Endpoint ID. responses: '200': description: Success. content: application/json: schema: type: object description: >- Response for updating endpoint assigned device software in bulk. required: - updated properties: updated: type: array description: >- List of endpoint IDs whose assigned device software was updated. items: type: string format: uuid description: Endpoint ID. errors: type: array description: Errors processing the request. items: type: object description: Error processing the request. required: - id - code properties: id: type: string format: uuid description: Endpoint ID. code: type: string description: Error code. '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/web-control/local-sites: get: x-soph-permissions: 'endpoint-state:read' tags: - Web Control summary: Get local sites description: Get all local sites. operationId: listLocalSitesByTenantId parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: List of local sites. content: application/json: schema: type: object required: - items - pages properties: items: type: array description: List of exclusion settings for local sites. items: type: object required: - id - url properties: id: description: Local site ID. type: string format: uuid categoryId: type: integer minimum: 1 maximum: 57 description: Local site category ID. tags: type: array items: type: string description: Tags associated with this local site. url: type: string description: Local site URL. comment: type: string description: Comment indicating why the local site was added. maxLength: 300 pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Add local site description: Adds a new local site. operationId: addLocalSiteExclusion parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: New local site request. content: application/json: schema: type: object required: - url properties: categoryId: type: integer minimum: 1 maximum: 57 description: >- Category ID associated with this local site. Either `categoryId` or `tags` must be provided. tags: type: array items: type: string minLength: 1 maxLength: 50 description: >- Array of tags associated with this local site setting. Either `categoryId` or `tags` must be provided. url: type: string minLength: 1 maxLength: 2048 comment: type: string maxLength: 300 example: categoryId: 50 url: 'https://www.example.com' comment: Reason for LocalSite Request responses: '201': description: Local site added. content: application/json: schema: type: object required: - id - url properties: id: description: Local site ID. type: string format: uuid categoryId: type: integer minimum: 1 maximum: 57 description: Local site category ID. tags: type: array items: type: string description: Tags associated with this local site. url: type: string description: Local site URL. comment: type: string description: Comment indicating why the local site was added. maxLength: 300 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/web-control/local-sites/{localSiteId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Web Control summary: Get a local site description: Get a local site by ID. operationId: getLocalSiteById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: localSiteId in: path description: Local site ID. required: true schema: type: string format: uuid responses: '200': description: Local site. content: application/json: schema: type: object required: - id - url properties: id: description: Local site ID. type: string format: uuid categoryId: type: integer minimum: 1 maximum: 57 description: Local site category ID. tags: type: array items: type: string description: Tags associated with this local site. url: type: string description: Local site URL. comment: type: string description: Comment indicating why the local site was added. maxLength: 300 '404': description: Can't find local site. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Update a local site description: Update a local site definition. operationId: updateLocalSiteSettingById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: localSiteId in: path description: Local site ID. required: true schema: type: string format: uuid requestBody: required: true description: Patch object to update a local site. content: application/json: schema: type: object properties: categoryId: type: integer minimum: 1 maximum: 57 description: >- Category ID associated with this local site. Either `categoryId` or `tags` must be provided. nullable: true tags: type: array items: type: string minLength: 1 maxLength: 50 description: >- Array of tags associated with this local site setting. Either `categoryId` or `tags` must be provided. nullable: true url: type: string minLength: 1 maxLength: 2048 comment: type: string maxLength: 300 nullable: true example: categoryId: 50 url: 'https://www.example.com' comment: Reason for LocalSitePatch Request responses: '200': description: Local site updated. content: application/json: schema: type: object required: - id - url properties: id: description: Local site ID. type: string format: uuid categoryId: type: integer minimum: 1 maximum: 57 description: Local site category ID. tags: type: array items: type: string description: Tags associated with this local site. url: type: string description: Local site URL. comment: type: string description: Comment indicating why the local site was added. maxLength: 300 '404': description: Can't find local site. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Delete local site description: Deletes the specified local site. operationId: deleteLocalSitesById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: localSiteId in: path description: Local site ID. required: true schema: type: string format: uuid responses: '200': description: >- Local site has been successfully deleted or is not present in this tenant. content: application/json: schema: type: object description: Response to a request to delete a specific local site. properties: deleted: description: Whether the local site was deleted. type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/web-control/categories: get: x-soph-permissions: 'endpoint-state:read' tags: - Web Control summary: Get web categories description: Get all Web Control categories. operationId: listWebControlCategories parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: List of Web Control categories. content: application/json: schema: type: array items: type: object required: - id - name - label properties: id: type: integer minimum: 0 maximum: 57 name: type: string label: type: string '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/web-control/tls-decryption: get: x-soph-permissions: 'endpoint-state:read' tags: - Web Control summary: Get TLS settings description: Get settings for SSL/TLS decryption of HTTPS websites. operationId: getWebDecryptionSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Web decryption settings. content: application/json: schema: type: object description: All settings for SSL/TLS decryption of HTTPS websites. properties: categories: type: array description: Web categories. uniqueItems: true items: type: object description: Web category for SSL/TLS decryption of HTTPS websites. properties: id: type: integer description: >- Web decryption category ID matching the Web Control categories. enum: - 10 - 14 - 20 - 27 - 54 name: type: string description: Mnemonic name of this category. label: type: string description: Human readable name of this category. decryptionEnabled: type: boolean description: >- Whether web decryption is enabled on websites in this category. excludedWebsites: type: object properties: itemsCount: type: integer minimum: 0 maximum: 500 total: type: integer minimum: 0 maximum: 500 items: type: array description: Websites excluded from decryption. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. properties: value: type: string description: 'Website IP address, IP address range or domain.' comment: type: string description: Comment indicating why the site was excluded. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Update TLS settings description: Update settings for SSL/TLS decryption of HTTPS websites. operationId: updateWebDecryptionSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Update web decryption settings. content: application/json: schema: type: object description: >- Update existing settings for SSL/TLS decryption of HTTPS websites. properties: categories: type: array description: Web categories. maxItems: 5 uniqueItems: true items: type: object required: - id - decryptionEnabled properties: id: type: integer description: >- Web decryption category ID matching the Web Control categories. enum: - 10 - 14 - 20 - 27 - 54 decryptionEnabled: type: boolean description: >- Whether web decryption is enabled on websites in this category. example: categories: - id: 10 decryptionEnabled: true responses: '200': description: Updated web decryption settings. content: application/json: schema: type: object description: All settings for SSL/TLS decryption of HTTPS websites. properties: categories: type: array description: Web categories. uniqueItems: true items: type: object description: Web category for SSL/TLS decryption of HTTPS websites. properties: id: type: integer description: >- Web decryption category ID matching the Web Control categories. enum: - 10 - 14 - 20 - 27 - 54 name: type: string description: Mnemonic name of this category. label: type: string description: Human readable name of this category. decryptionEnabled: type: boolean description: >- Whether web decryption is enabled on websites in this category. excludedWebsites: type: object properties: itemsCount: type: integer minimum: 0 maximum: 500 total: type: integer minimum: 0 maximum: 500 items: type: array description: Websites excluded from decryption. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. properties: value: type: string description: 'Website IP address, IP address range or domain.' comment: type: string description: Comment indicating why the site was excluded. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/web-control/tls-decryption/excluded-websites: get: x-soph-permissions: 'endpoint-state:read' tags: - Web Control summary: Get excluded sites description: List of websites excluded from SSL/TLS decryption. operationId: listWebDecryptionExcludedSites parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: List of excluded websites. content: application/json: schema: type: object description: Paged list of websites excluded from SSL/TLS decryption. required: - items - pages properties: items: type: array description: List of websites excluded from SSL/TLS decryption. items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. properties: value: type: string description: 'Website IP address, IP address range or domain.' comment: type: string description: Comment indicating why the site was excluded. pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Update websites description: Add and remove websites excluded from SSL/TLS decryption. operationId: updateWebDecryptionExcludedSites parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Update websites excluded from decryption. content: application/json: schema: type: object description: >- Patch object to add and/or remove websites excluded from decryption. properties: add: type: array description: Website to add to the exclusion list. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. required: - value properties: value: type: string description: 'Website IP address, IP address range or domain.' pattern: '^[-:0-9a-z./]{3,2048}$' comment: type: string description: Comment indicating why the site was excluded. pattern: '^[-\p{L}\p{Nl}\d ,.'']{0,300}$' remove: type: array description: Website to remove from the exclusion list. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. required: - value properties: value: type: string description: 'Website IP address, IP address range or domain.' pattern: '^[-:0-9a-z./]{3,2048}$' comment: type: string description: Comment indicating why the site was excluded. pattern: '^[-\p{L}\p{Nl}\d ,.'']{0,300}$' example: add: - value: 10.50.100.100 comment: Site had suspicious behaviour remove: - value: 10.50.100.100 comment: Site is safe now responses: '200': description: Updated web decryption exclusion list. content: application/json: schema: type: object description: >- Response to a previous request to update the list of websites excluded from decryption. properties: added: type: array description: Websites successfully added to the exclusion list. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. properties: value: type: string description: 'Website IP address, IP address range or domain.' comment: type: string description: Comment indicating why the site was excluded. removed: type: array description: Websites successfully removed from the exclusion list. maxItems: 500 items: type: object description: >- A website IP, range of IPs or domain to be excluded from SSL/TLS decryption of HTTPS websites. properties: value: type: string description: 'Website IP address, IP address range or domain.' comment: type: string description: Comment indicating why the site was excluded. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '422': description: The exclusions list would exceed the limit after update. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Web Control summary: Delete websites description: Clears the list of websites excluded from SSL/TLS decryption. operationId: clearWebDecryptionExcludedSites parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Cleared list of websites excluded from SSL/TLS decryption. content: application/json: schema: type: object description: >- Response to a request to clear the list of websites excluded from SSL/TLS decryption. properties: deleted: description: Whether the list was cleared. type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/tamper-protection: get: x-soph-permissions: 'endpoint-state:read' tags: - Global Tamper Protection summary: Globally turned on description: Check whether Tamper Protection is turned on globally. operationId: getTenantTamperProtectionSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Global Tamper Protection status. content: application/json: schema: type: object description: Global Tamper Protection settings. required: - enabled properties: enabled: type: boolean description: Whether Tamper Protection is turned on globally. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exclusions/scanning: get: x-soph-permissions: 'endpoint-state:read' tags: - Scanning Exclusions summary: Get exclusions description: Get all scanning exclusions. operationId: listScanningExclusions parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: type description: Scanning Exclusion type. required: false schema: type: string enum: - path - posixPath - virtualPath - process - web - pua - exploitMitigation - amsi - behavioral - journalHashingProcess - journalHashingPath - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: Page of scanning exclusions. content: application/json: schema: type: object required: - items - pages properties: items: type: array description: List of scanning exclusions. items: type: object required: - id - value - type - scanMode - lockedByManagingAccount properties: id: description: Unique ID for the scanning exclusion setting. type: string format: uuid value: description: Exclusion value. type: string type: type: string description: Scanning exclusion type. enum: - path - posixPath - virtualPath - process - web - pua - detectedExploit - amsi - behavioral - journalHashingProcess - journalHashingPath scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess description: description: Exclusion description added by the system. type: string comment: type: string description: Comment indicating why the exclusion was created. lockedByManagingAccount: description: >- Whether a partner manages the exclusion. 'true' means that only the partner can change or delete it. type: boolean pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Scanning Exclusions summary: Add exclusion description: Add a new scanning exclusion. operationId: addScanningExclusion parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Create a new scanning exclusion. required: - value - type properties: value: type: string description: Exclusion value. type: type: string description: Scanning exclusion type. enum: - path - posixPath - virtualPath - process - web - pua - detectedExploit - amsi - behavioral - journalHashingProcess - journalHashingPath scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess comment: type: string maxLength: 100 description: Comment indicating why the exclusion was created. example: value: Exclusion Value type: path scanMode: onDemand comment: Item is a Malware. responses: '201': description: Scanning exclusion added. content: application/json: schema: type: object required: - id - value - type - scanMode - lockedByManagingAccount properties: id: description: Unique ID for the scanning exclusion setting. type: string format: uuid value: description: Exclusion value. type: string type: type: string description: Scanning exclusion type. enum: - path - posixPath - virtualPath - process - web - pua - detectedExploit - amsi - behavioral - journalHashingProcess - journalHashingPath scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess description: description: Exclusion description added by the system. type: string comment: type: string description: Comment indicating why the exclusion was created. lockedByManagingAccount: description: >- Whether a partner manages the exclusion. 'true' means that only the partner can change or delete it. type: boolean '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: >- Forbidden. This may be due to scanning exclusions being managed at Partner/Enterprise level. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/exclusions/scanning/{exclusionId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Scanning Exclusions summary: Get an exclusion description: Get a scanning exclusion by ID. operationId: getScanningExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: Existing scanning exclusion. content: application/json: schema: type: object required: - id - value - type - scanMode - lockedByManagingAccount properties: id: description: Unique ID for the scanning exclusion setting. type: string format: uuid value: description: Exclusion value. type: string type: type: string description: Scanning exclusion type. enum: - path - posixPath - virtualPath - process - web - pua - detectedExploit - amsi - behavioral - journalHashingProcess - journalHashingPath scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess description: description: Exclusion description added by the system. type: string comment: type: string description: Comment indicating why the exclusion was created. lockedByManagingAccount: description: >- Whether a partner manages the exclusion. 'true' means that only the partner can change or delete it. type: boolean '404': description: Can't find scanning exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Scanning Exclusions summary: Update exclusion description: Update a scanning exclusion by ID. operationId: updateScanningExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid requestBody: description: Patch object to update the exclusion. required: true content: application/json: schema: type: object description: Updates an existing scanning exclusion. properties: value: type: string description: >- Exclusion value to be updated. Behavioral and Detected Exploit exclusions do not support updating this value. scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess comment: type: string nullable: true maxLength: 100 description: Comment indicating why the exclusion was created. example: value: Exclusion value scanMode: onDemand comment: Item is a Malware. responses: '200': description: Updated exclusion. content: application/json: schema: type: object required: - id - value - type - scanMode - lockedByManagingAccount properties: id: description: Unique ID for the scanning exclusion setting. type: string format: uuid value: description: Exclusion value. type: string type: type: string description: Scanning exclusion type. enum: - path - posixPath - virtualPath - process - web - pua - detectedExploit - amsi - behavioral - journalHashingProcess - journalHashingPath scanMode: type: string description: >- Default value of scan mode is "onDemandAndOnAccess" for exclusions of type path, posixPath and virtualPath, "onAccess" for process, web, pua, amsi. Behavioral and Detected Exploits (exploitMitigation) type exclusions do not support a scan mode. enum: - onDemand - onAccess - onDemandAndOnAccess description: description: Exclusion description added by the system. type: string comment: type: string description: Comment indicating why the exclusion was created. lockedByManagingAccount: description: >- Whether a partner manages the exclusion. 'true' means that only the partner can change or delete it. type: boolean '403': description: >- Forbidden. This may be due to scanning exclusions being managed at Partner/Enterprise level. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Scanning Exclusions summary: Delete exclusion description: Deletes a scanning exclusion. operationId: deleteScanningExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: Can't find exclusion or it has been successfully deleted. content: application/json: schema: type: object description: Response to a request to delete a specific scanning exclusion. properties: deleted: description: Whether the exclusion was deleted. type: boolean default: true '403': description: >- Forbidden. This may be due to scanning exclusions being managed at Partner/Enterprise level. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exploit-mitigation/detected-exploits: get: x-soph-permissions: 'endpoint-state:read' tags: - Exploit Mitigation summary: Detected exploits description: Get detected exploits and the number of each detected exploit. operationId: getDetectedExploits parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: thumbprintNotIn description: Filter out detected exploits with these thumbprints. required: false style: form explode: false schema: type: array items: type: string pattern: '[0-9a-zA-Z]{64}' responses: '200': description: List of detected exploits. content: application/json: schema: type: object required: - items - pages properties: items: type: array description: List of detected exploits. items: description: Exploit detected on one or more endpoints. type: object required: - id - thumbprint - count - description properties: id: description: Detected exploit ID. type: string format: uuid thumbprint: type: string pattern: '[0-9a-zA-Z]{64}' count: description: >- Number of times the same exploit has been detected, potentially across multiple endpoints. type: integer minimum: 1 description: description: >- The English description of the exploit detected event. type: string minLength: 1 maxLength: 2000 firstSeenAt: description: When the exploit was first seen. type: string format: date-time lastSeenAt: description: When the exploit was last seen. type: string format: date-time lastUser: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string lastEndpoint: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/exploit-mitigation/detected-exploits/{detectedExploitId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Exploit Mitigation summary: Detected exploit description: Get a detected exploit by ID. operationId: getDetectedExploitById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: detectedExploitId in: path description: ID of a previously detected exploit. required: true schema: type: string format: uuid responses: '200': description: Previously detected exploit. content: application/json: schema: description: Exploit detected on one or more endpoints. type: object required: - id - thumbprint - count - description properties: id: description: Detected exploit ID. type: string format: uuid thumbprint: type: string pattern: '[0-9a-zA-Z]{64}' count: description: >- Number of times the same exploit has been detected, potentially across multiple endpoints. type: integer minimum: 1 description: description: The English description of the exploit detected event. type: string minLength: 1 maxLength: 2000 firstSeenAt: description: When the exploit was first seen. type: string format: date-time lastSeenAt: description: When the exploit was last seen. type: string format: date-time lastUser: type: object description: User. required: - id properties: id: description: Unique ID for the user. type: string format: uuid name: description: Person's name. type: string lastEndpoint: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string '404': description: Can't find previously detected exploit. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exploit-mitigation/categories: get: x-soph-permissions: 'endpoint-state:read' tags: - Exploit Mitigation summary: Get categories description: Get Exploit Mitigation categories. operationId: getExploitMitigationCategories parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: List of Exploit Mitigation categories. content: application/json: schema: description: List of Exploit Mitigation categories. type: object required: - items properties: items: type: array items: description: Category of applications protected from exploits. type: object required: - id - name - settings properties: id: type: string description: Exploit Mitigation category ID. enum: - browsers - exclude - java - media - office - plugins - test - other name: description: Category name. type: string pattern: '[a-zA-Z ]{1,50}' settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: id: browsers name: Browsers settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exploit-mitigation/applications: get: x-soph-permissions: 'endpoint-state:read' tags: - Exploit Mitigation summary: Get applications description: Get Exploit Mitigation settings for all protected applications. operationId: getExploitMitigationApplications parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: type description: Exploit Mitigation Application type. required: false schema: type: string enum: - detected - custom - in: query name: modified description: Whether or not Exploit Mitigation Application has been customized. required: false schema: type: boolean responses: '200': description: List of Exploit Mitigation applications. content: application/json: schema: description: Page of applications protected by Exploit Mitigation. type: object required: - items - pages properties: items: type: array items: type: object required: - id - name - paths - category - type properties: id: description: ID of an Exploit Mitigation application. type: string format: uuid name: description: Name of this Exploit Mitigation application. type: string minLength: 1 maxLength: 1000 paths: description: >- Paths included in this Exploit Mitigation application. type: array maxItems: 100 items: type: string minLength: 1 maxLength: 260 category: type: string description: Exploit Mitigation category ID. enum: - browsers - exclude - java - media - office - plugins - test - other type: description: >- Whether the application was detected by the system or added by the user. type: string enum: - detected - custom modifications: description: >- Modifications made to the detected Exploit Mitigation Application. This object does not apply to when type is `custom`. type: object required: - protected properties: protected: description: >- Whether or not this Exploit Mitigation Application is protected. type: boolean default: true settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Exploit Mitigation summary: Add application description: Exclude a set of file paths from Exploit Mitigation. operationId: addExploitMitigationApplication parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Exclude a new application from Exploit Mitigation. content: application/json: schema: type: object required: - paths properties: paths: description: >- Array of absolute paths to an application file to exclude. You may use HitmanPro.Alert expansion variables (For example, $desktop, $programfiles). Currently, this array may contain only one application path. type: array items: type: string minLength: 1 maxLength: 260 minItems: 1 maxItems: 1 example: paths: - $programfiles\FooApp\foo.exe example: paths: - $programfiles\FooApp\foo.exe responses: '201': description: Custom Exploit Mitigation application created. content: application/json: schema: type: object required: - id - name - paths - category - type properties: id: description: ID of an Exploit Mitigation application. type: string format: uuid name: description: Name of this Exploit Mitigation application. type: string minLength: 1 maxLength: 1000 paths: description: Paths included in this Exploit Mitigation application. type: array maxItems: 100 items: type: string minLength: 1 maxLength: 260 category: type: string description: Exploit Mitigation category ID. enum: - browsers - exclude - java - media - office - plugins - test - other type: description: >- Whether the application was detected by the system or added by the user. type: string enum: - detected - custom modifications: description: >- Modifications made to the detected Exploit Mitigation Application. This object does not apply to when type is `custom`. type: object required: - protected properties: protected: description: >- Whether or not this Exploit Mitigation Application is protected. type: boolean default: true settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true '409': description: Custom Exploit Mitigation application already exists. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/exploit-mitigation/applications/{exploitMitigationApplicationId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Exploit Mitigation summary: Get application description: Get Exploit Mitigation settings for an application. operationId: getExploitMitigationApplicationById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exploitMitigationApplicationId in: path description: Exploit Mitigation application ID. required: true schema: type: string format: uuid responses: '200': description: Protected application. content: application/json: schema: type: object required: - id - name - paths - category - type properties: id: description: ID of an Exploit Mitigation application. type: string format: uuid name: description: Name of this Exploit Mitigation application. type: string minLength: 1 maxLength: 1000 paths: description: Paths included in this Exploit Mitigation application. type: array maxItems: 100 items: type: string minLength: 1 maxLength: 260 category: type: string description: Exploit Mitigation category ID. enum: - browsers - exclude - java - media - office - plugins - test - other type: description: >- Whether the application was detected by the system or added by the user. type: string enum: - detected - custom modifications: description: >- Modifications made to the detected Exploit Mitigation Application. This object does not apply to when type is `custom`. type: object required: - protected properties: protected: description: >- Whether or not this Exploit Mitigation Application is protected. type: boolean default: true settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true '404': description: Can't find protected application. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Exploit Mitigation summary: Update application description: Update Exploit Mitigation settings for an application. operationId: patchExploitMitigationApplicationById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exploitMitigationApplicationId in: path description: Exploit Mitigation application ID. required: true schema: type: string format: uuid requestBody: required: true description: Patch object to update the Exploit Mitigation application. content: application/json: schema: type: object description: >- Patch object to update the Exploit Mitigation application. For custom applications, you can only modify the `paths` property, the `modifications` property only apply to detected applications. properties: paths: description: >- Array of absolute paths to an application file to exclude. You may use HitmanPro.Alert expansion variables (For example, $desktop, $programfiles). Currently, this array may contain only one application path when modifying custom applications, detected applications may contain more than one path but you can't modify them. type: array items: type: string minLength: 1 maxLength: 260 minItems: 1 maxItems: 1 modifications: description: >- Modifications made to the detected Exploit Mitigation Application. This object does not apply when type is `custom`. Note that you can pass in one or more settings that apply to the category of this application, any settings that don't apply are disallowed and return a Bad Request. type: object properties: protected: description: >- Whether or not this Exploit Mitigation Application is protected. type: boolean default: true settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: AllSettings: modifications: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true DEP: true DeviceAndIoControl: true HeapSpray: false IAF: true Intruder: false KbdGuard: false LoadLib: false LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullCheck: true PreventEtwTampering: true SEHOP: true Caller: true StackExec: true StackPivot: true SomeSettings: modifications: protected: true settings: ASLR: true HeapSpray: true ProtectedTurnedOff: modifications: protected: false ProtectedTurnedOffAndSettingsModified: modifications: protected: true settings: ASLR: true StackExec: false ResetToUnModified: modifications: null example: paths: - $programfiles\FooApp\foo.exe modifications: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true DEP: true DeviceAndIoControl: true HeapSpray: false IAF: true Intruder: false KbdGuard: false LoadLib: false LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullCheck: true PreventEtwTampering: true SEHOP: true Caller: true StackExec: true StackPivot: true responses: '200': description: Exploit Mitigation exclusion updated. content: application/json: schema: type: object required: - id - name - paths - category - type properties: id: description: ID of an Exploit Mitigation application. type: string format: uuid name: description: Name of this Exploit Mitigation application. type: string minLength: 1 maxLength: 1000 paths: description: Paths included in this Exploit Mitigation application. type: array maxItems: 100 items: type: string minLength: 1 maxLength: 260 category: type: string description: Exploit Mitigation category ID. enum: - browsers - exclude - java - media - office - plugins - test - other type: description: >- Whether the application was detected by the system or added by the user. type: string enum: - detected - custom modifications: description: >- Modifications made to the detected Exploit Mitigation Application. This object does not apply to when type is `custom`. type: object required: - protected properties: protected: description: >- Whether or not this Exploit Mitigation Application is protected. type: boolean default: true settings: type: object additionalProperties: type: boolean example: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: false KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: true NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true example: protected: true settings: ASLR: true BannedAPI: true BottomUpASLR: true Caller: true DEP: true DeviceAndIoControl: true HeapSpray: true IAF: true Intruder: true KbdGuard: false LoadLib: true LockdownAutorun: true LockdownLoadImage: false LockdownNewFile: false NullPage: true PreventEtwTampering: true SEHOP: true StackExec: true StackPivot: true '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Exploit Mitigation summary: Delete application description: >- Deletes a custom (user-defined) Exploit Mitigation application by ID. Note you can only delete custom applications. A request to delete a system-detected application fails with a 409 Conflict message. operationId: deleteExploitMitigationApplicationById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exploitMitigationApplicationId in: path description: Exploit Mitigation application ID. required: true schema: type: string format: uuid responses: '200': description: >- Can't find Expolit Mitigation exclusion or it has been deleted successfully. content: application/json: schema: type: object description: >- Response to a request to delete an Exploit Mitigation application. properties: deleted: description: Whether the application was deleted. type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exclusions/intrusion-prevention: get: x-soph-permissions: 'endpoint-state:read' tags: - Intrusion Prevention summary: Intrusion Prevention description: Get all Intrusion Prevention exclusions. operationId: listIntrusionPreventionExclusions parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: Page of Intrusion Prevention exclusions. content: application/json: schema: description: Page of Intrusion Prevention exclusions. type: object required: - items - pages properties: items: type: array description: List of Intrusion Prevention exclusions. items: description: Intrusion Prevention exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string pattern: '[a-f0-9]{64}' type: type: string enum: - intrusionPrevention description: >- Exclusion type. This is always `intrusionPrevention`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: >- Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Remote addresses to exempt from Intrusion Prevention checks. items: type: string comment: description: Exclusion comment. type: string pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Intrusion Prevention summary: Intrusion Prevention description: Add a new Intrusion Prevention exclusion. operationId: addIntrusionPrevention parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: New Intrusion Prevention exclusion. content: application/json: schema: type: object description: >- To create a new Intrusion Prevention exclusion either localPorts, remotePorts or remoteAddress is needed. required: - direction properties: localPorts: description: Local protected ports. type: array minItems: 1 maxItems: 1 items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote protected ports. type: array minItems: 1 maxItems: 1 items: type: integer minimum: 1 maximum: 65535 direction: type: string description: Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array minItems: 1 maxItems: 1 description: >- Array of remote addresses for the intrusion prevention exclusion. items: type: string comment: description: Comment given to the exclusion at the time of creation. type: string example: localPorts: - 65232 remotePorts: - 65232 direction: inbound remoteAddresses: - 'http://10.50.100.100' comment: Item is a Malware responses: '201': description: Intrusion Prevention exclusion created. content: application/json: schema: description: Intrusion Prevention exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string pattern: '[a-f0-9]{64}' type: type: string enum: - intrusionPrevention description: Exclusion type. This is always `intrusionPrevention`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Remote addresses to exempt from Intrusion Prevention checks. items: type: string comment: description: Exclusion comment. type: string '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/exclusions/intrusion-prevention/{exclusionId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Intrusion Prevention summary: Intrusion Prevention description: Get an Intrusion Prevention exclusion by ID. operationId: getIntrusionPreventionExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: Intrusion Prevention exclusion. content: application/json: schema: description: Intrusion Prevention exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string pattern: '[a-f0-9]{64}' type: type: string enum: - intrusionPrevention description: Exclusion type. This is always `intrusionPrevention`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Remote addresses to exempt from Intrusion Prevention checks. items: type: string comment: description: Exclusion comment. type: string '404': description: Can't find Intrusion Prevention exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Intrusion Prevention summary: Intrusion Prevention description: Delete an Intrusion Prevention exclusion by ID. operationId: deleteIntrusionPreventionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: >- Can't find Intrusion Prevention exclusion or it has been deleted successfully. content: application/json: schema: type: object description: >- Response to a request to delete an Intrusion Prevention exclusion. properties: deleted: description: Whether the exclusion was deleted. type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Intrusion Prevention summary: Intrusion Prevention description: Update an Intrusion Prevention exclusion by ID. operationId: updateIntrusionPreventionExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid requestBody: description: Patch object to update the exclusion. required: true content: application/json: schema: type: object description: Update an existing Intrusion Prevention exclusion. properties: localPorts: description: Local protected ports. type: array maxItems: 1 items: type: integer minimum: 1 maximum: 65535 nullable: true remotePorts: description: Remote protected ports. type: array maxItems: 1 items: type: integer minimum: 1 maximum: 65535 nullable: true direction: type: string description: Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Array of remote addresses for the intrusion prevention exclusion. maxItems: 1 items: type: string nullable: true comment: description: Comment given to the exclusion at the time of creation. type: string nullable: true example: localPorts: - 65232 remotePorts: - 65232 direction: inbound remoteAddresses: - 'http://10.50.100.100' comment: Item is a Malware responses: '200': description: Updated exclusion. content: application/json: schema: description: Intrusion Prevention exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string pattern: '[a-f0-9]{64}' type: type: string enum: - intrusionPrevention description: Exclusion type. This is always `intrusionPrevention`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: Direction property of the intrusion prevention exclusion. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Remote addresses to exempt from Intrusion Prevention checks. items: type: string comment: description: Exclusion comment. type: string '404': description: Can't find Intrusion Prevention exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/exclusions/isolation: get: x-soph-permissions: 'endpoint-state:read' tags: - Isolation Exclusions summary: Get exclusions description: Get all isolation exclusions. operationId: listIsolationExclusions parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': description: Page of isolation exclusions. content: application/json: schema: description: Page of isolation exclusions. type: object required: - items - pages properties: items: type: array description: List of isolation exclusions. items: description: Isolation exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string format: uuid type: type: string enum: - isolation description: Exclusion type. This is always `isolation`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: >- Remote addresses to exempt from isolation restrictions. items: type: string comment: description: Exclusion comment. type: string pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-state:update' tags: - Isolation Exclusions summary: Isolation Exclusions description: Adds a new Isolation exclusion. operationId: addIsolationExclusion parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: New Isolation exclusion. content: application/json: schema: description: Isolation exclusion request. type: object required: - direction properties: localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: Remote addresses to exempt from isolation restrictions. items: type: string comment: description: Exclusion comment. type: string example: localPorts: - 65535 remotePorts: - 65535 direction: inbound remoteAddresses: - 'http://10.50.100.100' comment: Item is a Malware responses: '201': description: Isolation exclusion added. content: application/json: schema: description: Isolation exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string format: uuid type: type: string enum: - isolation description: Exclusion type. This is always `isolation`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: Remote addresses to exempt from isolation restrictions. items: type: string comment: description: Exclusion comment. type: string '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/exclusions/isolation/{exclusionId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Isolation Exclusions summary: Isolation Exclusion description: Get a single Isolation exclusion by ID. operationId: getIsolationExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: Isolation exclusion. content: application/json: schema: description: Isolation exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string format: uuid type: type: string enum: - isolation description: Exclusion type. This is always `isolation`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: Remote addresses to exempt from isolation restrictions. items: type: string comment: description: Exclusion comment. type: string '404': description: Can't find Isolation exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-state:update' tags: - Isolation Exclusions summary: Delete exclusion description: Deletes an Isolation exclusion. operationId: deleteIsolationExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid responses: '200': description: Can't find Isolation exclusion or it has been successfully deleted. content: application/json: schema: type: object description: Response to a request to delete an isolation exclusion. properties: deleted: description: Whether the exclusion was deleted. type: boolean default: true '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Isolation Exclusions summary: Update exclusion description: Updates an Isolation exclusion by ID. operationId: updateIsolationExclusionById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: exclusionId in: path description: Exclusion ID. required: true schema: type: string format: uuid requestBody: description: Patch object to update exclusion. required: true content: application/json: schema: type: object description: Update an existing isolation exclusion. properties: localPorts: description: Local protected ports. type: array items: type: integer minimum: 1 maximum: 65535 nullable: true remotePorts: description: Remote protected ports. type: array items: type: integer minimum: 1 maximum: 65535 nullable: true direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: Remote addresses to exempt from isolation restrictions. maxItems: 1 items: type: string nullable: true comment: description: Comment given to the exclusion at the time of creation. type: string nullable: true example: localPorts: - 65535 remotePorts: - 65535 direction: inbound remoteAddresses: - 'http://10.50.100.100' comment: Item is a Malware responses: '200': description: Updated Isolation exclusion. content: application/json: schema: description: Isolation exclusion. type: object required: - id - type - direction - comment properties: id: description: Exclusion ID. type: string format: uuid type: type: string enum: - isolation description: Exclusion type. This is always `isolation`. localPorts: description: Local allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 remotePorts: description: Remote allowed ports. type: array items: type: integer minimum: 1 maximum: 65535 direction: type: string description: IP traffic direction. enum: - inbound - outbound - both remoteAddresses: type: array description: Remote addresses to exempt from isolation restrictions. items: type: string comment: description: Exclusion comment. type: string '404': description: Can't find Isolation exclusion. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/peripheral-control/peripherals: get: x-soph-permissions: 'endpoint-state:read' tags: - Peripheral Control summary: Get peripherals description: Get all peripherals. operationId: getPeripheralsByTenantId parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: lastSeenAfter description: >- Find peripherals that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive). examples: FullUtcTimestamp: value: '2021-02-23T12:34:56.700Z' DateOnly: value: '2021-02-23' Duration: value: '-PT4H500S' summary: '4 hours and 500 seconds ago, value is case-sensitive' DaysOnly: value: '-P1D' summary: one day ago HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: '-PT200S' summary: 200 seconds ago required: false schema: type: string maxLength: 24 - in: query name: lastSeenBefore description: >- Find peripherals that were last seen strictly before the given date and time (UTC) or a duration relative to the current date and time. Peripherals last seen exactly at the specified time are excluded. examples: FullUtcTimestamp: value: '2021-02-23T12:34:56.700Z' DateOnly: value: '2021-02-23' Duration: value: '-PT4H500S' summary: '4 hours and 500 seconds ago, value is case-sensitive' DaysOnly: value: '-P1D' summary: one day ago HoursOnly: value: '-PT2H' summary: 2 hours ago MinutesOnly: value: '-PT20M' summary: 20 minutes ago SecondsOnly: value: '-PT200S' summary: 200 seconds ago required: false schema: type: string maxLength: 24 - in: query name: type description: One or more peripheral types to include. required: false style: form explode: false schema: type: array items: type: string description: Peripheral type. enum: - opticalDrive - floppyDrive - modem - encryptedStorage - infrared - wireless - removableStorage - bluetooth - mtp - camera responses: '200': description: List of peripherals. content: application/json: schema: type: object description: Page of peripherals. required: - items - pages properties: items: type: array description: Array of peripherals objects. items: type: object description: Peripheral. required: - id - type - category - model - modelId properties: id: type: string description: >- Universally unique peripheral ID assigned by Sophos Central. format: uuid type: type: string description: Peripheral type. enum: - opticalDrive - floppyDrive - modem - encryptedStorage - infrared - wireless - removableStorage - bluetooth - mtp - camera category: type: string description: Peripheral category. enum: - storage - network - media model: type: string description: >- Peripheral model as reported by the associated endpoint. maxLength: 250 modelId: type: string description: >- Peripheral model ID as reported by the associated endpoint. maxLength: 250 instanceId: type: string description: >- Peripheral instance ID as reported by the associated endpoint. maxLength: 250 lastEndpoint: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string lastUsedBy: type: string description: >- Name or login of last known user of this peripheral, if available. maxLength: 100 lastActionTaken: type: string description: Peripheral control action. enum: - alertedOnly - readOnly - blocked firstSeenAt: type: string description: When this peripheral was first detected. format: date-time lastSeenAt: type: string description: When this peripheral was last detected. format: date-time example: id: eb6c74a0-8bc2-4b88-9030-b547db0f2832 type: wireless category: network model: Apple Wireless Network Adapter (802.11 a∕b∕g∕n∕ac) modelId: 5AC-AIRPORT-19910ED94C48 instanceId: 'INS:5AC-AIRPORT-19910ED94C48' lastEndpointHostname: John's iMac lastUsedBy: John's iMac\johndoe lastActionTaken: allowed firstSeenAt: '2020-10-29T11:03:57.000Z' lastSeenAt: '2021-01-17T16:00:06.000Z' pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/peripheral-control/peripherals/{peripheralId}': get: x-soph-permissions: 'endpoint-state:read' tags: - Peripheral Control summary: Get a peripheral description: Get a peripheral by ID. operationId: getPeripheralById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: peripheralId in: path description: Peripheral ID. required: true schema: type: string format: uuid responses: '200': description: Peripheral. content: application/json: schema: type: object description: Peripheral. required: - id - type - category - model - modelId properties: id: type: string description: >- Universally unique peripheral ID assigned by Sophos Central. format: uuid type: type: string description: Peripheral type. enum: - opticalDrive - floppyDrive - modem - encryptedStorage - infrared - wireless - removableStorage - bluetooth - mtp - camera category: type: string description: Peripheral category. enum: - storage - network - media model: type: string description: Peripheral model as reported by the associated endpoint. maxLength: 250 modelId: type: string description: >- Peripheral model ID as reported by the associated endpoint. maxLength: 250 instanceId: type: string description: >- Peripheral instance ID as reported by the associated endpoint. maxLength: 250 lastEndpoint: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string lastUsedBy: type: string description: >- Name or login of last known user of this peripheral, if available. maxLength: 100 lastActionTaken: type: string description: Peripheral control action. enum: - alertedOnly - readOnly - blocked firstSeenAt: type: string description: When this peripheral was first detected. format: date-time lastSeenAt: type: string description: When this peripheral was last detected. format: date-time example: id: eb6c74a0-8bc2-4b88-9030-b547db0f2832 type: wireless category: network model: Apple Wireless Network Adapter (802.11 a∕b∕g∕n∕ac) modelId: 5AC-AIRPORT-19910ED94C48 instanceId: 'INS:5AC-AIRPORT-19910ED94C48' lastEndpointHostname: John's iMac lastUsedBy: John's iMac\johndoe lastActionTaken: allowed firstSeenAt: '2020-10-29T11:03:57.000Z' lastSeenAt: '2021-01-17T16:00:06.000Z' '404': description: Can't find peripheral. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /settings/migration: get: x-soph-permissions: - 'endpoint-migration:read' tags: - Migrations summary: Get settings description: Get the endpoint migration settings for this tenant. operationId: getMigrationSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Migration settings. content: application/json: schema: type: object required: - enabled - expiresAt description: Endpoint migration settings for this tenant. properties: enabled: description: True if migrations are enabled for this account. type: boolean expiresAt: description: >- This is the time at which migrations will be disabled. It is recommended to limit this to as long as you need to run migrations. Set to 2099-01-01T00:00:00.000Z when enabled indefinitely. type: string format: date-time '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/settings/event-journal/{endpointType}': get: x-soph-permissions: 'endpoint-state:read' tags: - Event Journal summary: Get current settings description: Get all event journal settings. operationId: getEventJournalSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointType in: path required: true description: Endpoint type. schema: format: enum type: string description: Supported endpoint type. enum: - computer - server responses: '200': description: Retrieved event journal settings. content: application/json: schema: type: object description: Current event journal settings for a customer. required: - useRecommended - diskSpaceLimitInMB - diskSpaceLimitAsPercentage properties: useRecommended: description: Shows if the recommended setting is being used. type: boolean diskSpaceLimitInMB: type: object required: - recommendedValue properties: recommendedValue: type: integer format: int32 minimum: 300 maximum: 30000 description: Maximum size of the event journal (MB). value: type: integer format: int32 minimum: 300 maximum: 30000 description: Maximum size of the event journal (MB). diskSpaceLimitAsPercentage: type: object required: - recommendedValue properties: recommendedValue: type: integer format: int32 multipleOf: 10 minimum: 0 maximum: 40 description: >- Disk space limit for the event journal (percentage). The value 0 will mean Disk space limit is not specified. Supported values [0, 10, 20, 30, 40]. value: type: integer format: int32 multipleOf: 10 minimum: 0 maximum: 40 description: >- Disk space limit for the event journal (percentage). The value 0 will mean Disk space limit is not specified. Supported values [0, 10, 20, 30, 40]. example: useRecommended: true diskSpaceLimitInMB: recommendedValue: 5250 value: 8000 diskSpaceLimitAsPercentage: recommendedValue: 0 value: 10 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Authentication required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Customer not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Event Journal summary: Update settings description: >- Update settings for event journal size and disk space limits. If you specify both a maximum disk space and a maximum journal size, the lower of these limits is used. operationId: updateEventJournalSettings parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointType in: path required: true description: Endpoint type. schema: format: enum type: string description: Supported endpoint type. enum: - computer - server requestBody: required: true description: Update event journal settings. content: application/json: schema: type: object description: Update event journal settings. required: - useRecommended properties: useRecommended: description: Shows if the recommended setting is required. type: boolean diskSpaceLimitInMB: type: integer format: int32 minimum: 300 maximum: 30000 description: Maximum size of the event journal (MB). diskSpaceLimitAsPercentage: type: integer format: int32 multipleOf: 10 minimum: 0 maximum: 40 description: >- Disk space limit for the event journal (percentage). The value 0 will mean Disk space limit is not specified. Supported values [0, 10, 20, 30, 40]. example: useRecommended: false diskSpaceLimitInMB: 15000 diskSpaceLimitAsPercentage: 20 responses: '200': description: Event journal settings updated. content: application/json: schema: type: object description: Current event journal settings for a customer. required: - useRecommended - diskSpaceLimitInMB - diskSpaceLimitAsPercentage properties: useRecommended: description: Shows if the recommended setting is being used. type: boolean diskSpaceLimitInMB: type: object required: - recommendedValue properties: recommendedValue: type: integer format: int32 minimum: 300 maximum: 30000 description: Maximum size of the event journal (MB). value: type: integer format: int32 minimum: 300 maximum: 30000 description: Maximum size of the event journal (MB). diskSpaceLimitAsPercentage: type: object required: - recommendedValue properties: recommendedValue: type: integer format: int32 multipleOf: 10 minimum: 0 maximum: 40 description: >- Disk space limit for the event journal (percentage). The value 0 will mean Disk space limit is not specified. Supported values [0, 10, 20, 30, 40]. value: type: integer format: int32 multipleOf: 10 minimum: 0 maximum: 40 description: >- Disk space limit for the event journal (percentage). The value 0 will mean Disk space limit is not specified. Supported values [0, 10, 20, 30, 40]. example: useRecommended: false diskSpaceLimitInMB: recommendedValue: 5250 value: 15000 diskSpaceLimitAsPercentage: recommendedValue: 0 value: 20 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Authentication required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Customer not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /endpoints/isolation: post: x-soph-permissions: 'endpoint-state:update' tags: - Endpoint Isolation summary: Isolation update description: >- Turn on or off endpoint isolation for multiple endpoints. We recommend that you wait for a period of time between turning endpoint isolation on and off using this API. operationId: bulkUpdateEndpointIsolation parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: >- Request to set the desired isolation state for multiple endpoints. required: - enabled - ids properties: enabled: description: Whether the endpoints should be isolated or not. type: boolean comment: description: Reason the endpoints should be isolated or not. type: string maxLength: 400 ids: description: List of endpoints IDs. type: array items: type: string format: uuid minItems: 1 maxItems: 500 examples: EndpointBulkIsolationRequest: value: enabled: true comment: Isolating endpoints with suspicious health ids: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 - 9d5d6819-0238-43e6-ba03-815cae0d474d - 2da8b591-9164-4f7e-a367-ad9b9cb77736 - 66046f6a-bff0-4b51-aa0b-ac18bd363207 responses: '202': description: >- Isolation update requests have been processed. Accepted requests are returned in `items`, and rejected requests are returned in `errors`. content: application/json: schema: type: object description: >- Response to a request to set the desired isolation state for multiple endpoints. properties: items: description: List of endpoint isolation requests that were accepted. type: array items: type: object description: >- Endpoint ID and corresponding endpoint isolation details. properties: id: description: Endpoint ID. type: string format: uuid isolation: type: object description: >- Response to a request to set the desired isolation state of an endpoint. required: - enabled properties: enabled: description: Whether the endpoint should be isolated or not. type: boolean lastEnabledAt: description: >- When isolation was last enabled for the endpoint. type: string format: datetime lastEnabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid lastDisabledAt: description: >- When isolation was last disabled for the endpoint. type: string format: datetime lastDisabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid comment: description: Reason endpoint should be isolated or not. type: string maxLength: 400 errors: description: >- List of endpoint isolation requests that could not be accepted. type: array items: type: object description: >- Error details for an endpoint action request that could not be accepted for a specific endpoint. required: - id - errorCode - errorMessage properties: id: description: The endpoint id. type: string format: uuid errorCode: type: string description: >- 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. enum: - notFound - notSupported - conflict - permissionDenied - internalError errorMessage: description: >- A human-readable error message describing the error in more detail. type: string maxLength: 250 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: No endpoints found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Isolation or removal from isolation in progress. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoints/{endpointId}/isolation': get: x-soph-permissions: 'endpoint-state:read' tags: - Endpoint Isolation summary: Get isolation description: Get isolation settings for an endpoint. operationId: getEndpointIsolationById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid responses: '200': description: Endpoint isolation settings. content: application/json: schema: type: object description: >- Response to a request to set the desired isolation state of an endpoint. required: - enabled properties: enabled: description: Whether the endpoint should be isolated or not. type: boolean lastEnabledAt: description: When isolation was last enabled for the endpoint. type: string format: datetime lastEnabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid lastDisabledAt: description: When isolation was last disabled for the endpoint. type: string format: datetime lastDisabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid comment: description: Reason endpoint should be isolated or not. type: string maxLength: 400 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-state:update' tags: - Endpoint Isolation summary: Update isolation description: Update isolation settings for an endpoint. operationId: updateEndpointIsolationById parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: endpointId in: path description: Endpoint ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Request to set the desired isolation state for an endpoint. required: - enabled properties: enabled: description: Whether the endpoint should be isolated or not. type: boolean comment: description: Reason endpoint should be isolated or not. type: string maxLength: 400 examples: EndpointIsolationEnable: value: enabled: true comment: Isolating Foo-PC EndpointIsolationEnableNoComment: value: enabled: true EndpointIsolationDisable: value: enabled: false comment: Removing Foo-PC from isolation responses: '200': description: Updated Endpoint isolation settings. content: application/json: schema: type: object description: >- Response to a request to set the desired isolation state of an endpoint. required: - enabled properties: enabled: description: Whether the endpoint should be isolated or not. type: boolean lastEnabledAt: description: When isolation was last enabled for the endpoint. type: string format: datetime lastEnabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid lastDisabledAt: description: When isolation was last disabled for the endpoint. type: string format: datetime lastDisabledBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid comment: description: Reason endpoint should be isolated or not. type: string maxLength: 400 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find endpoint. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Isolation or removal from isolation in progress. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /migrations: get: x-soph-permissions: 'endpoint-migration:read' tags: - Migrations summary: Gets all migrations description: Gets all migration jobs for the tenant. operationId: getMigrationJobs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: mode description: Filter migration jobs by sending or receiving mode. required: false schema: type: string enum: - sending - receiving - in: query name: page required: false description: 'The page number to fetch, starting with 1.' schema: type: integer default: 1 - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 500 maximum: 1000 minimum: 1 - in: query name: pageTotal description: >- Whether the number of pages should be calculated and returned in the response. required: false schema: type: boolean default: false responses: '200': description: Gets all migration jobs. content: application/json: schema: type: object description: Paged list of migration jobs. required: - items - pages properties: items: type: array description: List of migration jobs. items: type: object required: - id - createdAt - expiresAt - mode description: Migration job details. properties: id: description: Migration job ID. type: string format: uuid token: description: Job token. type: string mode: type: string description: >- Whether the tenant is sending or receiving endpoints. enum: - sending - receiving createdAt: description: When the job was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid expiresAt: description: When the migration job expires. type: string format: date-time example: id: c83bc7f6-7c93-4aa4-ac73-006bd5a5884a token: >- eyJmb28iOiJ434833989debe92389we9e8debe902392388ede982372309099de9999a0a7732736611222fff2f1f212fffef3f592983iYXIifQo= mode: receiving createdAt: '2021-04-22T15:32:28.482Z' expiresAt: '2021-04-29T15:32:28.482Z' pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-migration:create' tags: - Migrations summary: Start migration job description: Start a migration job in the receiving tenant. operationId: createReceivingMigrationJob parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: A request to create a receiving migration job. required: true content: application/json: schema: type: object description: Request to create a migration job. required: - fromTenant - endpoints properties: fromTenant: description: Sending tenant. type: string format: uuid endpoints: description: Endpoints that will be migrated to this tenant. type: array items: type: string format: uuid minItems: 1 maxItems: 1000 examples: NewMigrationJob: value: fromTenant: 48bebbb0-f7b6-49c5-aec0-315858f73457 endpoints: - cb5bb918-8aee-4cad-b21b-875d1f6938b2 - 30fd930b-5325-46b7-842b-3c6e93c99947 - 70941003-9859-40d9-88ae-de3fcd1f527e - 91c52a76-78bf-4bed-9446-b9e91f814940 - 1fc3237d-823c-451a-8726-f83ec9e1fe13 responses: '201': description: Migration job created. content: application/json: schema: type: object required: - id - createdAt - expiresAt - mode description: Migration job details. properties: id: description: Migration job ID. type: string format: uuid token: description: Job token. type: string mode: type: string description: Whether the tenant is sending or receiving endpoints. enum: - sending - receiving createdAt: description: When the job was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid expiresAt: description: When the migration job expires. type: string format: date-time example: id: c83bc7f6-7c93-4aa4-ac73-006bd5a5884a token: >- eyJmb28iOiJ434833989debe92389we9e8debe902392388ede982372309099de9999a0a7732736611222fff2f1f212fffef3f592983iYXIifQo= mode: receiving createdAt: '2021-04-22T15:32:28.482Z' expiresAt: '2021-04-29T15:32:28.482Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/migrations/{migrationJobId}': get: x-soph-permissions: 'endpoint-migration:read' tags: - Migrations summary: Gets a migration job description: Get a single migration job. operationId: getMigrationJob parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: migrationJobId in: path description: Migration job ID. required: true schema: type: string format: uuid responses: '200': description: Migration job. content: application/json: schema: type: object required: - id - createdAt - expiresAt - mode description: Migration job details. properties: id: description: Migration job ID. type: string format: uuid token: description: Job token. type: string mode: type: string description: Whether the tenant is sending or receiving endpoints. enum: - sending - receiving createdAt: description: When the job was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid expiresAt: description: When the migration job expires. type: string format: date-time example: id: c83bc7f6-7c93-4aa4-ac73-006bd5a5884a token: >- eyJmb28iOiJ434833989debe92389we9e8debe902392388ede982372309099de9999a0a7732736611222fff2f1f212fffef3f592983iYXIifQo= mode: receiving createdAt: '2021-04-22T15:32:28.482Z' expiresAt: '2021-04-29T15:32:28.482Z' '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Migration job not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri put: x-soph-permissions: 'endpoint-migration:create' tags: - Migrations summary: Start migration job description: Start a migration job in the sending tenant. operationId: createSendingMigrationJob parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: migrationJobId in: path description: Migration job ID. required: true schema: type: string format: uuid requestBody: description: A request to create a sending migration job. required: true content: application/json: schema: type: object description: Request to create a migration job. required: - token - endpoints properties: token: description: Job token. type: string endpoints: description: Endpoints that will be migrated to this tenant. type: array items: type: string format: uuid minItems: 1 maxItems: 1000 examples: StartMigrationJob: value: token: eyJ0b2tlbiI6ICJUaGlzIGlzIG9ubHkgYSBzYW1wbGUgdG9rZW4uIn0= endpoints: - cb5bb918-8aee-4cad-b21b-875d1f6938b2 - 30fd930b-5325-46b7-842b-3c6e93c99947 - 70941003-9859-40d9-88ae-de3fcd1f527e - 91c52a76-78bf-4bed-9446-b9e91f814940 - 1fc3237d-823c-451a-8726-f83ec9e1fe13 responses: '200': description: Migration job already created. content: application/json: schema: type: object required: - id - createdAt - expiresAt - mode description: Migration job details. properties: id: description: Migration job ID. type: string format: uuid token: description: Job token. type: string mode: type: string description: Whether the tenant is sending or receiving endpoints. enum: - sending - receiving createdAt: description: When the job was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid expiresAt: description: When the migration job expires. type: string format: date-time example: id: c83bc7f6-7c93-4aa4-ac73-006bd5a5884a token: >- eyJmb28iOiJ434833989debe92389we9e8debe902392388ede982372309099de9999a0a7732736611222fff2f1f212fffef3f592983iYXIifQo= mode: receiving createdAt: '2021-04-22T15:32:28.482Z' expiresAt: '2021-04-29T15:32:28.482Z' '201': description: Migration job created. content: application/json: schema: type: object required: - id - createdAt - expiresAt - mode description: Migration job details. properties: id: description: Migration job ID. type: string format: uuid token: description: Job token. type: string mode: type: string description: Whether the tenant is sending or receiving endpoints. enum: - sending - receiving createdAt: description: When the job was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal Email or clientId. type: string type: description: Principal type. type: string format: enum enum: - user - service - system name: description: User Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid expiresAt: description: When the migration job expires. type: string format: date-time example: id: c83bc7f6-7c93-4aa4-ac73-006bd5a5884a token: >- eyJmb28iOiJ434833989debe92389we9e8debe902392388ede982372309099de9999a0a7732736611222fff2f1f212fffef3f592983iYXIifQo= mode: receiving createdAt: '2021-04-22T15:32:28.482Z' expiresAt: '2021-04-29T15:32:28.482Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/migrations/{migrationJobId}/endpoints': get: x-soph-permissions: 'endpoint-migration:read' tags: - Migrations summary: Migration endpoints description: Gets the status of endpoints that are being migrated. operationId: getMigrationEndpoints parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: page required: false description: 'The page number to fetch, starting with 1.' schema: type: integer default: 1 - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 500 maximum: 1000 minimum: 1 - in: query name: pageTotal description: >- Whether the number of pages should be calculated and returned in the response. required: false schema: type: boolean default: false - name: migrationJobId in: path description: Migration job ID. required: true schema: type: string format: uuid responses: '200': description: Migration endpoints. content: application/json: schema: type: object description: Paged list of endpoints for a migration job. required: - items - pages properties: items: type: array description: List of migration jobs. items: type: object required: - id - status description: Endpoint details. properties: id: description: Endpoint ID from the sending tenant. type: string format: uuid status: type: string description: Migration status. enum: - pending - failed - succeeded newId: description: New endpoint ID in the receiving tenant. type: string format: uuid migratedAt: description: When the endpoint was migrated. type: string format: date-time failedAt: description: When the endpoint failed to migrate. type: string format: date-time reason: description: Why the endpoint failed to migrate. type: string pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /policies: get: x-soph-permissions: 'endpoint-policy:read' summary: Get policies description: Get policies of a tenant. operationId: getPolicies tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: policyType description: Policy type. schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Page of policies. content: application/json: schema: type: object description: List of policies. required: - items - pages properties: items: description: List of policies. type: array items: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-policy:create' summary: Create policy description: Create new policy. operationId: createPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Request to create a new policy. required: - name - type properties: name: description: Policy name. type: string pattern: '^\S(?:.*\S)?$' maxLength: 100 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation priority: description: Policy priority. type: integer enabled: description: Whether the policy is turned on. type: boolean disableAt: description: When the policy should be turned off. type: string format: date-time appliesTo: type: object settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 examples: CreatePolicyMinimal: value: name: New Policy 1 type: threat-protection CreatePolicyNotEnabled: value: name: New Policy 1 type: threat-protection enabled: false CreateTemporaryPolicy: value: name: New Policy 1 type: threat-protection disableAt: '2021-10-01T22:00:01.000Z' CreateServerPolicyWithDefaultSettings: value: name: Server Policy 1 type: server-threat-protection appliesTo: endpoints: - e6aaf537-e501-40c9-92ae-65bd2fd8cf94 - 3a22affe-a609-4183-b8c7-29d45d09ee3b - 023d1240-7cb4-4153-a11f-a2506c3fa283 CreateUserPolicyWithHighPriority: value: name: 'Block Acme app for Alice, Bob and all of HR' type: application-control appliesTo: users: - 02c68ba7-333f-4bb3-bc19-099cda989903 - c7968490-40fa-49cd-923b-8fc58e54a8a7 userGroups: - 34bc62f9-5d7e-41cf-afb7-edbf02c8614b priority: 999 settings: endpoint.application-control.controlled-applications: value: - Acme - AcmeUpdater CreatePolicyNotAppliedToAnyUserOrEndpoint: value: name: New Policy type: device-encryption priority: 10 enabled: true disableAt: '2021-10-01T22:00:01.000Z' appliesTo: {} settings: endpoint.device-encryption.allow-network-unlock: value: true endpoint.device-encryption.enable-right-click-context-menu: value: false endpoint.device-encryption.encrypt-non-boot-volumes: value: true endpoint.device-encryption.require-startup-authentication: value: false responses: '201': description: New policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /policies/settings: get: x-soph-permissions: 'endpoint-policy:read' summary: Get metadata description: Supported metadata. operationId: getSettingMetadatas tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: policyType description: Policy type. schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption responses: '200': description: List of setting metadatas. content: application/json: schema: type: object description: List of metadata for the setting. required: - items properties: version: description: Metadata version. type: string pattern: '^20\d{2}-\d{2}-\d{2}' schemas: description: Object schemas. type: object additionalProperties: type: object description: Object schema in a subset of json-schema format. properties: type: type: string description: Object type. Only `"object"` is supported. enum: - object description: type: string description: Object schema description. properties: type: object description: Object properties. additionalProperties: type: object description: Object schema property. properties: type: type: string description: Object schema property type. enum: - boolean - integer - string - array description: type: string description: Object schema property description. additionalProperties: true required: type: array description: List of required property names. items: type: string required: - type - description - properties - required items: description: List of metadata for the setting. type: array items: type: object description: List of metadata for settings in the policy type. required: - items properties: type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation items: description: List of metadata for settings. type: array items: type: object description: Setting metadata. required: - name - description - type - defaultValue properties: name: description: Setting name. type: string description: description: Setting description. type: string type: type: string description: Type of setting items. enum: - boolean - string - integer - object - arrayOfBooleans - arrayOfStrings - arrayOfIntegers - arrayOfObjects useValidOnlyInBasePolicy: description: >- Whether this setting can only be used by the base policy. type: boolean useValidOnlyInAdditionalPolicies: description: >- Whether this setting can only be used by additional policies. type: boolean readOnlyInBasePolicy: description: >- Whether this setting is read-only in the base policy. type: boolean readOnlyInAdditionalPolicies: description: >- Whether this setting is read-only in additional policies. type: boolean schema: type: string description: >- Setting schema. Applies only when `type` is `object` or `arrayOfObjects`. pattern: '^[a-z]+[a-zA-Z]+$' defaultValue: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. allowedValues: type: array items: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. defaultFormat: description: Format of setting item value. type: string pattern: '^[a-z][a-zA-Z0-9]{0,24}$' allowedFormats: type: array items: description: Format of setting item value. type: string pattern: '^[a-z][a-zA-Z0-9]{0,24}$' defaultUnit: description: Unit of setting item value. type: string pattern: '^[a-z][a-zA-Z0-9]{0,24}$' allowedUnits: type: array items: description: Unit of setting item value. type: string pattern: '^[a-z][a-zA-Z0-9]{0,24}$' limit: type: object description: Limit values of a setting. required: - min - max properties: min: description: Minimum value of the setting. type: integer max: description: Maximum value of the setting. type: integer parent: description: The parent's setting key. type: string examples: description: Examples of the setting. type: array items: type: string '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}': get: x-soph-permissions: 'endpoint-policy:read' summary: Get policy description: Policy details. operationId: getPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid responses: '200': description: Details of the requested policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-policy:update OR endpoint-policy:assign' summary: Update policy description: >- Update policy. Note you can only change the settings for a base policy and roles with only assignment permissions can only change the ChangeUsersOrDevicesPolicyAppliesTo field. operationId: updatePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Input to update a policy. properties: name: description: Policy name. type: string pattern: '^\S(?:.*\S)?$' maxLength: 100 priority: description: Policy priority. type: integer enabled: description: Whether the policy is turned on. type: boolean disableAt: description: >- When the policy should be turned off. Set to null to remove the scheduled disable time. type: string format: date-time nullable: true appliesTo: type: object settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 examples: ChangePolicyName: value: name: Block Acme app ChangePolicyPriority: value: priority: 19 DisablePolicy: value: enabled: false EnablePolicyTemporarily: value: enabled: true disableAt: '2021-10-01T22:00:01.000Z' ChangeUsersOrDevicesPolicyAppliesTo: value: enabled: true priority: 12 appliesTo: users: - 02c68ba7-333f-4bb3-bc19-099cda989903 - c7968490-40fa-49cd-923b-8fc58e54a8a7 userGroups: - 34bc62f9-5d7e-41cf-afb7-edbf02c8614b ChangePolicyNameAndSettings: value: name: Block Acme app settings: endpoint.device-encryption.encrypt-non-boot-volumes: value: true ChangePolicySettings: value: settings: endpoint.device-encryption.require-startup-authentication: value: false responses: '200': description: Updated policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '400': description: >- Bad request. If it is a base policy, then only settings can be updated. If the role of the caller only has assignment permissions, then only appliesTo field can be updated. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Can't update base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-policy:delete' summary: Delete policy description: Delete policy. operationId: deletePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid responses: '200': description: Policy is deleted. content: application/json: schema: type: object description: Deletion result. properties: deleted: description: Whether deletion is successful. type: boolean '409': description: >- Can't delete base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}/settings': get: x-soph-permissions: 'endpoint-policy:read' summary: Get settings description: Policy settings. operationId: getSettingsOfPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid responses: '200': description: List of the settings in a policy. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-policy:update' summary: Update settings description: Update policy settings. operationId: updateSettingsOfPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 examples: UpdateDeviceEncryptionSettings: value: endpoint.device-encryption.encrypt-non-boot-volumes: value: true endpoint.device-encryption.require-startup-authentication: value: false responses: '200': description: Updated settings. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Can't update base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}/settings/reset': post: x-soph-permissions: 'endpoint-policy:update' summary: Reset settings description: Reset policy settings. operationId: resetPolicySettings tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid responses: '200': description: Reset policy settings. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Can't reset base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}/settings/{settingKey}': get: x-soph-permissions: 'endpoint-policy:read' summary: Get setting description: Get the value of a setting key in a policy. operationId: getValueOfSettingKeyInPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid - in: path name: settingKey description: Setting key. required: true schema: type: string pattern: '^[-a-z0-9.]+$' example: endpoint.device-encryption.encrypt-non-boot-volumes responses: '200': description: Value of the setting key. content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}/settings/{settingKey}/reset': post: x-soph-permissions: 'endpoint-policy:update' summary: Reset setting description: Reset a setting to its default value. operationId: resetSettingInPolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid - in: path name: settingKey description: Setting key. required: true schema: type: string pattern: '^[-a-z0-9.]+$' example: endpoint.device-encryption.encrypt-non-boot-volumes responses: '200': description: The resetted setting. content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Can't reset base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyId}/clone': post: x-soph-permissions: 'endpoint-policy:create' summary: Clone policy description: Clone policy. operationId: clonePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyId description: Policy ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object description: Input to clone a policy. properties: name: description: Name of the newly cloned policy. type: string pattern: '^\S(?:.*\S)?$' maxLength: 100 examples: ClonePolicy: value: name: Block "Acme" (cloned) ClonePolicyAutoGenerateName: value: {} responses: '201': description: Cloned policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base': get: x-soph-permissions: 'endpoint-policy:read' summary: Get base description: Get base policy for a policy type. operationId: getBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption responses: '200': description: Base policy for policy type. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-policy:update' summary: Update base policy description: Update base policy. Note that only settings can be changed. operationId: updateBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption requestBody: required: true content: application/json: schema: type: object description: Input to update a base policy. properties: settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 examples: ChangeBasePolicySettings: value: settings: endpoint.device-encryption.encrypt-non-boot-volumes: value: true endpoint.device-encryption.require-startup-authentication: value: false responses: '200': description: Updated base policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Can't update base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base/settings': get: x-soph-permissions: 'endpoint-policy:read' summary: Get settings description: Get settings of the base policy for a policy type. operationId: getSettingsOfBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption responses: '200': description: Settings of a base policy. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-policy:update' summary: Update settings description: Update settings in the base policy for a policy type. operationId: updateSettingsOfBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption requestBody: required: true content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 examples: UpdateDeviceEncryptionSettings: value: endpoint.device-encryption.encrypt-non-boot-volumes: value: true endpoint.device-encryption.require-startup-authentication: value: false responses: '200': description: Updated settings for base policy. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '409': description: >- Can't update base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base/settings/reset': post: x-soph-permissions: 'endpoint-policy:update' summary: Reset settings description: Reset the settings in a base policy. operationId: resetBasePolicySettings tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption responses: '200': description: Reset base policy settings. content: application/json: schema: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 '409': description: Can't reset base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base/settings/{settingKey}': get: x-soph-permissions: 'endpoint-policy:read' summary: Get setting description: Get the value of a setting in the base policy for a policy type. operationId: getValueOfSettingItemInBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption - in: path name: settingKey description: Setting key. required: true schema: type: string pattern: '^[-a-z0-9.]+$' example: endpoint.device-encryption.encrypt-non-boot-volumes responses: '200': description: Setting value of a key in the base policy. content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find setting value. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-policy:update' summary: Update setting description: Update a setting in the base policy. operationId: updateValueOfSettingItemInBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption - in: path name: settingKey description: Setting key. required: true schema: type: string pattern: '^[-a-z0-9.]+$' example: endpoint.device-encryption.encrypt-non-boot-volumes requestBody: required: true content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. examples: BooleanSetting: value: value: true UpdateDeviceEncryptionSettings: value: endpoint.device-encryption.encrypt-non-boot-volumes: value: true endpoint.device-encryption.require-startup-authentication: value: false responses: '200': description: Updated setting. content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. '404': description: Setting key not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Can't update base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base/settings/{settingKey}/reset': post: x-soph-permissions: 'endpoint-policy:update' summary: Reset setting description: Reset a setting in the base policy to its default value. operationId: resetSettingInBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption - in: path name: settingKey description: Setting key. required: true schema: type: string pattern: '^[-a-z0-9.]+$' example: endpoint.device-encryption.encrypt-non-boot-volumes responses: '200': description: The reset setting. content: application/json: schema: type: object properties: comment: type: string maxLength: 100 description: User comment explaining why this setting value was chosen. '404': description: Setting key not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Can't reset base policies and policies locked by a managing account. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/policies/{policyType}/base/clone': post: x-soph-permissions: 'endpoint-policy:create' summary: Clone base description: Clone a new policy from the base policy for a policy type. operationId: cloneBasePolicy tags: - Policy Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: policyType description: Policy type. required: true schema: type: string enum: - threat-protection - peripheral-control - application-control - data-collection-and-investigation - device-encryption - web-control - agent-updating - windows-firewall - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation example: device-encryption requestBody: required: true content: application/json: schema: type: object description: Input to clone a policy. properties: name: description: Name of the newly cloned policy. type: string pattern: '^\S(?:.*\S)?$' maxLength: 100 examples: ClonePolicy: value: name: Block "Acme" (cloned) ClonePolicyAutoGenerateName: value: {} responses: '201': description: Cloned policy. content: application/json: schema: type: object description: Policy details. required: - id - name - type - lockedByManagingAccount - priority - tenant - enabled - settings properties: id: description: Unique API identifier for the policy. type: string format: uuid name: description: Policy name. type: string maxLength: 50 type: type: string description: Policy type. enum: - threat-protection - peripheral-control - application-control - web-control - agent-updating - windows-firewall - device-encryption - data-collection-and-investigation - endpoint-dns-protection - server-threat-protection - server-peripheral-control - server-application-control - server-web-control - server-lockdown - server-agent-updating - server-windows-firewall - server-file-integrity-monitoring - server-linux-runtime-detection - server-data-collection-and-investigation lockedByManagingAccount: description: >- Whether the policy is managed by a partner or organization, 'true' mean yes. type: boolean priority: description: Policy priority. type: integer tenant: description: Tenant these resources belong to. type: object required: - id properties: id: type: string format: uuid name: type: string enabled: description: Whether the policy is turned on. type: boolean settings: type: object description: >- Keys have specific names documented [here](https://developer.sophos.com/endpoint-policy-settings-all). additionalProperties: type: object properties: comment: type: string maxLength: 100 description: >- User comment explaining why this setting value was chosen. example: endpoint.malware.enabled: value: true recommendedValue: true sophosManaged: true endpoint.scans.scheduled.days: format: string value: - monday - wednesday - friday endpoint.scans.scheduled.hour: value: '21:00' endpoint.scans.scheduled.start-from: value: '2020-05-13T21:00:01.000Z' format: date-time endpoint.disk-encryption.key-expiration: value: 24 unit: hours recommendedValue: 48 appliesTo: type: object disableAt: description: When the policy should be turned off. type: string format: date-time createdAt: description: Time the policy was created. type: string format: date-time createdBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid updatedAt: description: Time the policy was last updated. type: string format: date-time updatedBy: type: object required: - id - type properties: id: description: Principal ID. type: string type: description: Type of the Principal. type: string format: enum enum: - user - service name: description: Principal name. type: string accountType: type: string description: Account type. enum: - partner - tenant - organization accountId: description: Account ID. type: string format: uuid '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /endpoint-groups: get: x-soph-permissions: 'endpoint-groups:read' summary: Query groups description: Endpoint groups in the directory. operationId: listTenantEndpointGroups tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: groupType description: Endpoint group type. required: false schema: type: string enum: - computer - server - in: query name: sort description: >- Sort criteria for endpoint groups. Valid sort fields are `id`, `name`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: The size of the page requested. required: false schema: type: integer default: 50 maximum: 500 minimum: 1 - in: query name: ids description: IDs to match. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: search description: Search term. required: false schema: type: string pattern: '^[^#,+"\\<>;]+$' - in: query name: searchFields description: >- Search your specified fields. The default is to search group names only. required: false style: form explode: false schema: type: array items: type: string enum: - name - description - in: query name: endpointIds description: Endpoint UUIDs. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 responses: '200': description: A page of endpoint groups. content: application/json: schema: type: object description: Endpoint groups. required: - items - pages properties: items: type: array items: type: object description: Endpoint group in the directory. required: - id - name - type - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpoints: type: object description: Associated endpoints. properties: total: description: Total number of endpoints in this group. type: integer itemsCount: description: Total number of items in the list. type: integer items: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid createdAt: description: When the group was created. type: string format: date-time updatedAt: description: When the group was last updated. type: string format: date-time pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-groups:create' summary: Add new group description: Add new endpoint group to the directory. operationId: createTenantEndpointGroup tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New group request. required: true content: application/json: schema: type: object description: Add a new endpoint group to the directory. required: - name - type properties: name: description: Group name. type: string minLength: 1 maxLength: 250 pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string maxLength: 1000 pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpointIds: description: Endpoints in the group. type: array items: type: string format: uuid uniqueItems: true maxItems: 1000 examples: CreateComputerGroup: value: name: Seattle computers description: User devices in Seattle office type: computer endpointIds: - e6a03d34-a943-45b7-8de3-deaf38864be4 - b7e5f3aa-a7c6-43c6-a65e-3cd52008464b - f0316f62-6ce7-4008-99c5-6a1c209ab494 CreateServerGroup: value: name: Finance servers description: Servers for generating finance reports type: server endpointIds: - 78a76bbc-1488-450a-a4df-ffb056a00ad8 - 2269ca83-d97d-490f-a73a-3c9bc648ad8f CreateEmptyServerGroup: value: name: Servers 1 type: server responses: '201': description: Endpoint group created. content: application/json: schema: type: object description: Endpoint group in the directory. required: - id - name - type - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpoints: type: object description: Associated endpoints. properties: total: description: Total number of endpoints in this group. type: integer itemsCount: description: Total number of items in the list. type: integer items: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid createdAt: description: When the group was created. type: string format: date-time updatedAt: description: When the group was last updated. type: string format: date-time '404': description: At least one endpoint in the request not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Group names must be unique. You also can't use this API to add endpoints to a group synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoint-groups/types/{groupType}': get: x-soph-permissions: 'endpoint-groups:read' summary: Get groups by type description: Endpoint groups of your specified type in the directory. operationId: listTenantEndpointGroupsByGroupType tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupType description: Endpoint group type. required: true schema: type: string enum: - computer - server example: computer - in: query name: sort description: >- Sort criteria for endpoint groups. Valid sort fields are `id`, `name`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: The size of the page requested. required: false schema: type: integer default: 50 maximum: 500 minimum: 1 - in: query name: ids description: IDs to match. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: search description: Search term. required: false schema: type: string pattern: '^[^#,+"\\<>;]+$' - in: query name: searchFields description: >- Search your specified fields. The default is to search group names only. required: false style: form explode: false schema: type: array items: type: string enum: - name - description - in: query name: endpointIds description: Endpoint UUIDs. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 responses: '200': description: A page of endpoint groups. content: application/json: schema: type: object description: Endpoint groups. required: - items - pages properties: items: type: array items: type: object description: Endpoint group in the directory. required: - id - name - type - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpoints: type: object description: Associated endpoints. properties: total: description: Total number of endpoints in this group. type: integer itemsCount: description: Total number of items in the list. type: integer items: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid createdAt: description: When the group was created. type: string format: date-time updatedAt: description: When the group was last updated. type: string format: date-time pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoint-groups/{groupId}': get: x-soph-permissions: 'endpoint-groups:read' summary: Get group description: Get endpoint group by ID. operationId: getTenantEndpointGroupById tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid responses: '200': description: The endpoint group. content: application/json: schema: type: object description: Endpoint group in the directory. required: - id - name - type - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpoints: type: object description: Associated endpoints. properties: total: description: Total number of endpoints in this group. type: integer itemsCount: description: Total number of items in the list. type: integer items: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid createdAt: description: When the group was created. type: string format: date-time updatedAt: description: When the group was last updated. type: string format: date-time '404': description: Endpoint group not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-groups:delete' summary: Delete group description: Delete endpoint group. operationId: deleteTenantEndpointGroupById tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid responses: '200': description: Group deleted. content: application/json: schema: type: object description: Endpoint group deleted. required: - deleted properties: deleted: type: boolean '409': description: >- You can only delete empty groups with no members. You also can't use this API to delete groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'endpoint-groups:update' summary: Update group description: Update endpoint group. operationId: patchTenantEndpointGroup tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid requestBody: description: A patch object to update the endpoint group. required: true content: application/json: schema: type: object description: Update endpoint group. properties: name: description: New group name. type: string minLength: 1 maxLength: 250 pattern: '^[^#,+"\\<>;]+$' description: description: New group description. type: string maxLength: 1000 pattern: '^[^#,+"\\<>;]+$' examples: UpdateGroupName: value: name: Finance servers UpdateGroupDescription: value: description: Servers for generating finance reports UpdateGroupNameAndDescription: value: name: Finance servers description: Servers for generating finance reports responses: '200': description: Endpoint group updated. content: application/json: schema: type: object description: Endpoint group in the directory. required: - id - name - type - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string pattern: '^[^#,+"\\<>;]+$' description: description: Group description. type: string pattern: '^[^#,+"\\<>;]+$' type: description: Endpoint group types. type: string format: enum enum: - computer - server endpoints: type: object description: Associated endpoints. properties: total: description: Total number of endpoints in this group. type: integer itemsCount: description: Total number of items in the list. type: integer items: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid createdAt: description: When the group was created. type: string format: date-time updatedAt: description: When the group was last updated. type: string format: date-time '404': description: Endpoint group not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Group names must be unique. You also can't use this API to update groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoint-groups/{groupId}/endpoints': get: x-soph-permissions: 'endpoint-groups:read' summary: Endpoints in group description: Returns the endpoints in your specified group. operationId: listTenantEndpointsByEndpointGroupId tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid - in: query name: sort description: >- Defines how to sort the data. We are temporarily stopping support for this parameter until further notice. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: lastSeenAt OneFieldSort: value: 'lastSeenAt:asc' MoreThanOneTermSort: value: 'lastSeenAt:asc,hostname:desc' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: The size of the page requested. required: false schema: type: integer default: 50 maximum: 500 minimum: 1 - in: query name: search description: >- Term to search for in the specified search fields. We are temporarily stopping support for this parameter until further notice. required: false schema: type: string - in: query name: searchFields description: >- List of search fields for finding the given search term. Defaults to all applicable fields. We are temporarily stopping support for this parameter until further notice. style: form explode: false required: false schema: type: array items: type: string enum: - hostname - groupName - associatedPersonName - ipAddresses - osName responses: '200': description: A page of endpoints. content: application/json: schema: type: object required: - items - pages properties: items: type: array description: List of endpoints. items: type: object required: - id - type - hostname - os properties: id: description: Unique ID for the endpoint. type: string format: uuid type: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. hostname: description: Hostname of the endpoint. type: string health: type: object description: Health status of an endpoint. required: - overall - threats - services properties: overall: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown threats: type: object description: Threats on the endpoint. required: - status properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown services: type: object description: Status of services on the endpoint. required: - status - serviceDetails properties: status: type: string description: >- Health status of an endpoint or a service running on an endpoint. enum: - good - suspicious - bad - unknown serviceDetails: description: Details of services on the endpoint. type: array items: type: object required: - name - status properties: name: description: Service name. type: string status: type: string description: Status of a service on an endpoint. enum: - running - stopped - missing os: type: object description: OS information. required: - platform - name properties: isServer: description: Whether the OS is a server OS. type: boolean platform: type: string description: OS platform type. enum: - windows - linux - macOS name: description: OS name as reported by the endpoint. type: string majorVersion: description: OS major version. type: integer minorVersion: description: OS minor version. type: integer build: description: OS build. type: integer ipv4Addresses: description: List of IPv4 addresses. type: array items: type: string ipv6Addresses: description: List of IPv6 addresses. type: array items: type: string macAddresses: description: List of MAC addresses. type: array items: type: string group: type: object description: Endpoint group. properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid groupHierarchy: description: >- List of groups in the hierarchy, starting with the group the endpoint is in and ending with the top-level group. type: array items: type: object description: A single group in the endpoint group hierarchy. required: - name - id properties: name: description: Endpoint group name. type: string id: description: Unique ID for endpoint group. type: string format: uuid parentId: description: >- Unique ID of the parent group. Omitted for the top-level group. type: string format: uuid example: name: Group B id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 example: - name: Data Team id: 7ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - name: Backend Team id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 parentId: 550e8400-e29b-41d4-a716-446655440000 - name: Engineering id: 550e8400-e29b-41d4-a716-446655440000 associatedPerson: type: object description: Person associated with an endpoint. properties: name: description: Person's name. type: string viaLogin: description: Person's login on the endpoint. type: string id: description: Unique ID for the Person. type: string format: uuid tamperProtectionSupported: description: Whether the endpoint supports Tamper Protection. type: boolean tamperProtectionEnabled: description: Whether Tamper Protection is turned on. type: boolean assignedProducts: description: Products assigned to the endpoint. type: array items: type: object required: - code - version properties: code: type: string description: Endpoint product. enum: - coreAgent - interceptX - xdr - endpointProtection - deviceEncryption - mtr - ztna version: description: Version of a product assigned to an endpoint. type: string status: type: string description: >- Installation status of a product assigned to the endpoint. enum: - installed - notInstalled packages: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string deviceSoftware: type: object description: Choice of device software available to the endpoint. properties: protection: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string ztna: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string encryption: description: Device software. type: object properties: assignedId: description: >- The ID of the currently installed device software. type: string name: description: >- The name of the currently installed device software. type: string status: type: string description: Device software status. enum: - assigned - unassigned - unlicensed - unsupported - upgradable available: type: array items: description: The available device software. type: object properties: id: description: The ID of the available device software. type: string name: description: >- The name of the available device software. type: string lastSeenAt: description: >- Date and time (UTC) when the endpoint last communicated with Sophos Central. example: '2019-09-23T12:02:01.700Z' type: string lastOsUpdateAt: description: >- Date and time (UTC) when the endpoint last applied an operating system update. example: '2025-02-23T12:02:01.700Z' type: string serialNumber: description: >- The hardware/BIOS serial number of the endpoint. Only Mac endpoints report their serial number currently. example: P28DA81LMD5T type: string encryption: type: object description: Endpoint encryption state. required: - volumes properties: volumes: description: Endpoint volumes. type: array items: type: object description: Endpoint volume encryption status. required: - volumeId - status properties: volumeId: description: Endpoint volume ID. type: string status: type: string description: Endpoint volume encryption status. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - unknown overallStatus: type: string description: The overall encryption status of the endpoint. enum: - notEncrypted - encrypted - encrypting - notSupported - suspended - notAvailable - unmanaged lockdown: type: object description: Server Lockdown status. required: - status properties: status: type: string description: >- Server lockdown status. Please note that the following statuses are no longer used: `creatingWhitelist`, `installing`, `registering`, and `starting` are now reported as `locking`; `stopping` is reported as `locked`; and `uninstalled` is reported as `unlocked`. enum: - creatingWhitelist - installing - locked - notInstalled - registering - starting - stopping - unavailable - uninstalled - unlocked - locking tags: description: List of tags. type: array maxItems: 15 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. online: description: Whether endpoint is currently online. type: boolean cloud: type: object description: Endpoint cloud. required: - provider - instanceId properties: provider: type: string description: Cloud provider in which the endpoint is running. enum: - aws - azure instanceId: description: Unique ID for the cloud instance. type: string pattern: '^([0-9a-zA-Z-_]{1,64})' isolation: type: object description: Endpoint isolation state as reported by an endpoint. required: - status properties: status: type: string description: Isolation status reported by endpoint. enum: - isolated - notIsolated adminIsolated: description: Whether isolation was triggered by an admin. type: boolean selfIsolated: description: >- Whether isolation was triggered by the endpoint itself. type: boolean cloned: description: >- Whether the endpoint has been cloned by another endpoint. type: boolean lastAgentUpdateAt: description: >- Date and time (UTC) when the agent was last successfully updated. example: '2019-09-23T12:02:01.700Z' type: string pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: >- (Optional) The total number of items on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. '404': description: Group not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'endpoint-groups:update' summary: Add to group description: Add endpoints to your group. operationId: addMultipleEndpointsToGroup tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid requestBody: description: Request to add multiple endpoints to a group. required: true content: application/json: schema: type: object description: Add endpoints to a group. required: - ids properties: ids: description: List of endpoint IDs. type: array items: type: string format: uuid uniqueItems: true maxItems: 1000 examples: AddMultipleEndpointsToGroup: value: ids: - e6a03d34-a943-45b7-8de3-deaf38864be4 - b7e5f3aa-a7c6-43c6-a65e-3cd52008464b - f0316f62-6ce7-4008-99c5-6a1c209ab494 - 03e3b79e-b482-4e24-9166-b61a7eaa68b2 - 7cd499ea-c7d9-4186-9859-a3c10b87c042 responses: '201': description: Endpoints added to the specified group. content: application/json: schema: type: object description: Endpoints added to the group. properties: addedEndpoints: description: Endpoints added. type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string errors: type: object description: Can't add endpoints to a group. properties: endpointsNotFound: type: array items: type: string format: uuid endpointsOfWrongType: type: array items: type: string format: uuid '404': description: Group or at least one endpoint in the request not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- You can't modify groups synced from Active Directory. You also can't use this API to add endpoints synced from Active Directory to a group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-groups:update' summary: Remove from group description: Remove endpoints from a group. operationId: removeMultipleEndpointsFromGroup tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid - in: query name: ids description: Endpoint IDs. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 responses: '200': description: Endpoints removed from group. content: application/json: schema: type: object description: Removed endpoints from a group. properties: removedEndpoints: type: array items: type: object description: Reference to an endpoint. required: - id properties: id: description: Unique endpoint ID. type: string format: uuid hostname: description: Endpoint hostname. type: string errors: type: object description: Can't remove endpoints from a group. properties: endpointsNotFound: type: array items: type: string format: uuid '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/endpoint-groups/{groupId}/endpoints/{endpointId}': delete: x-soph-permissions: 'endpoint-groups:update' summary: Remove from group description: Remove endpoint from a group. operationId: removeSingleEndpointFromGroup tags: - Endpoint Groups Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Endpoint group ID. required: true schema: type: string format: uuid - in: path name: endpointId description: Endpoint ID. required: true schema: type: string format: uuid responses: '200': description: Endpoint removed from group. content: application/json: schema: type: object description: Removed endpoint from a group. properties: removed: type: boolean '404': description: Group not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- You can't use this API to modify groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /software/packages/recommended: get: x-soph-permissions: 'endpoint-versions:read' tags: - Packages summary: Recommended packages description: Get all Sophos Recommended packages for the tenant. operationId: getRecommendedPackages parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: All sophos recommended packages. content: application/json: schema: type: object description: Sophos recommended packages. required: - items properties: items: type: array description: Sophos recommended packages. items: type: object description: Sophos recommended package. required: - id - platform - modules properties: id: type: string description: Sophos recommended package ID. example: recommended-winserv platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /software/packages/static: get: x-soph-permissions: 'endpoint-versions:read' tags: - Packages summary: Get static packages description: Get all static packages available for the tenant. operationId: getStaticPackages parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' - name: endpointType in: query required: false description: Show static packages by endpoint type. schema: type: string enum: - computer - server - name: platform in: query required: false description: Filter to the platform of the static package. schema: type: string enum: - windows - linux - macOS - name: type in: query required: false description: Show the type of static package. schema: description: Static package type. type: string enum: - fixed - special - lts - name: expiresFrom description: Show static packages that expire on or after this date (inclusive). in: query required: false schema: type: string format: date - name: expiresTo description: Show static packages that expire before this date (exclusive). in: query required: false schema: type: string format: date - name: releasedFrom in: query required: false description: >- Show static packages that were released on or after this date (inclusive). schema: type: string format: date - name: releasedTo in: query required: false description: >- Show static packages that were released before this date (exclusive). schema: type: string format: date responses: '200': description: All static packages. content: application/json: schema: type: object description: Static packages. required: - items properties: items: type: array description: Static packages. items: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/software/packages/static/{staticPackageId}': get: x-soph-permissions: 'endpoint-versions:read' tags: - Packages summary: Get static package description: Get an individual static package. operationId: getStaticPackage parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: staticPackageId description: Static package ID. in: path required: true schema: type: string format: uuid responses: '200': description: Static package. content: application/json: schema: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. '400': description: Bad Request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Static package not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/software/packages/static/{staticPackageId}/add': post: x-soph-permissions: 'endpoint-versions:update' tags: - Packages summary: Add special package description: >- Add a special package by token, supplied by Sophos support. This is a one-way operation. operationId: addSpecialStaticPackage parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: staticPackageId description: Static package ID. in: path required: true schema: type: string format: uuid responses: '201': description: Special package successfully added. content: application/json: schema: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Token does not map to a released and active special package. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Special package has already been added. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /software/comments: get: x-soph-permissions: 'endpoint-versions:read' tags: - Packages summary: Get comments description: Get all comments. operationId: getComments parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: All comments. content: application/json: schema: type: object description: List of comments. required: - items properties: items: type: array description: List of comments. items: type: object description: A comment for a static package. required: - package - id - comment properties: package: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. id: type: string format: uuid description: ID of the static package. comment: type: string description: >- Descriptive comment associated with the static package. example: Use this static package for special servers '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/software/comments/{staticPackageId}': get: x-soph-permissions: 'endpoint-versions:read' tags: - Packages summary: Get package comment description: Get the static package comment. operationId: getComment parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: staticPackageId description: Static package ID. in: path required: true schema: type: string format: uuid responses: '200': description: Comment. content: application/json: schema: type: object description: A comment for a static package. required: - package - id - comment properties: package: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. id: type: string format: uuid description: ID of the static package. comment: type: string description: Descriptive comment associated with the static package. example: Use this static package for special servers '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Comment and/or static package not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri put: x-soph-permissions: 'endpoint-versions:update' tags: - Packages summary: Update comment description: Add/Update the static package comment. operationId: updateComment parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: staticPackageId description: Static package ID. in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object description: Update comment for a static package. required: - comment properties: comment: type: string pattern: '^[-\p{L}\p{N}\s,.]+$' minLength: 1 maxLength: 5000 description: >- The comment (can only include hyphens, letters, digits, spaces, tabs, line breaks, commas, or dots). responses: '200': description: Comment updated. content: application/json: schema: type: object description: A comment for a static package. required: - package - id - comment properties: package: type: object description: Static package. required: - id - name - releasedAt - expiresAt - type - platform - modules - visible properties: id: type: string format: uuid description: Static package ID. name: type: string description: Static package description. releasedAt: type: string format: date description: Static package publication date. example: '2022-10-12' expiresAt: type: string format: date description: Static package expiration date. example: '2022-02-12' type: description: Static package type. type: string enum: - fixed - special - lts platform: type: string description: OS platform type. enum: - windows - linux - macOS endpointType: type: string description: >- Endpoint type. Please note that the type `securityVm` is no longer used. enum: - computer - server - securityVm modules: type: array description: Endpoint modules in this static package. items: type: object description: Single endpoint module. required: - name - version properties: name: type: string description: The installed endpoint module. enum: - coreAgent - deviceEncryption - interceptX - mdr version: type: string description: Module version. example: name: coreAgent version: 2022.1.0.40 packageNotesUrl: type: string format: uri description: Link to the static package release notes. visible: type: boolean description: >- If the software package is visible and assignable to policies. id: type: string format: uuid description: ID of the static package. comment: type: string description: Descriptive comment associated with the static package. example: Use this static package for special servers '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Comment and/or static package not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'endpoint-versions:update' tags: - Packages summary: Delete comment description: Delete the static package comment. operationId: deleteComment parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: staticPackageId description: Static package ID. in: path required: true schema: type: string format: uuid responses: '200': description: Comment deleted. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean description: Package deleted. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Comment and/or static package not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /tags/assignment: post: x-soph-permissions: >- endpoint-computer-tag-management:write OR endpoint-server-tag-management:write summary: Assign and unassign tags description: Assign and unassign tags to endpoints. operationId: tagAssignment tags: - Endpoint Tags parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Update tag assignments request. required: true content: application/json: schema: type: object description: >- The tags to assign and unassign from entities. At least one of assign, unassign or unassignAll must be provided. Only one of unassign or unassignAll can be used in the same request. allOf: - type: object description: >- Tag assignment input fields, excluding entity IDs. At least one of assign, unassign or unassignAll must be provided. Only one of unassign or unassignAll can be used in the same request. When a request includes both assign and unassign/unassignAll, unassignments are always applied before assignments. properties: assign: description: List of tags to assign. type: array uniqueItems: true minItems: 0 maxItems: 15 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. unassign: description: List of tags to unassign. type: array uniqueItems: true minItems: 0 maxItems: 1000 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. unassignAll: description: Set to `true` to unassign all tags. type: boolean enum: - true - type: object required: - entityIds properties: entityIds: description: List of entityIds to be assigned to and unassigned from. type: array uniqueItems: true minItems: 1 maxItems: 1000 items: type: string format: uuid example: entityIds: - 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11 - 28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12 - 38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13 unassign: - key: Country value: USA - key: Department value: Finance assign: - key: Project value: Apollo - key: Department value: HR - key: Country value: UK - key: Region value: '' responses: '200': description: Success. content: application/json: schema: type: object description: >- Response for tag assignment operations with detailed error information for partial failures. properties: items: type: array description: >- Array of entity IDs that were successfully processed with no failures. Only present when there are successful entities. minItems: 1 items: type: string format: uuid errors: type: array description: >- Detailed error information for entities that had failures. Only present when there are errors. minItems: 1 items: type: object description: >- Error information for an entity that had failures during tag assignment operations. required: - entityId - status properties: entityId: type: string format: uuid description: The entity ID that had failures. status: type: string enum: - failed - partial description: >- Status of operations for this entity. `failed` indicates all operations failed for this entity. `partial` indicates some operations succeeded, some failed. assigned: type: array description: Tags that were successfully assigned to this entity. minItems: 1 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. unassigned: type: array description: >- Tags that were successfully unassigned from this entity. minItems: 1 items: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. tagErrors: type: array description: >- Per-tag operation failures for this entity. **Note:** The server implementation will cap this array at 100 entries per entity. If an entity has more than 100 tag errors, only the first 100 will be included in the response. Errors are ordered by priority (most critical first): ENTITY_NOT_FOUND, WOULD_EXCEED_MAX_TAGS, TAG_KEY_CONFLICT, TAG_OWNED_BY_THIRD_PARTY, TAG_ALREADY_IN_STATE. This ensures the most important errors are included when the array is truncated. minItems: 1 maxItems: 100 items: type: object description: >- Error information for a specific tag operation that failed. required: - tag - operation - code properties: tag: type: object description: >- Tagging object that can be applied to multiple types of devices or other objects. required: - key - value properties: key: type: string description: >- A tag key. Between 1 and 40 characters which must not include colons. pattern: '^[^:]{1,40}$' value: type: string description: >- A tag value between 0 and 40 characters which must not include colons. pattern: '^[^:]{0,40}$' displayString: type: string description: A tag display string. pattern: '^([^:]{1,40}):([^:]{0,40})$' tagOrigin: type: string readOnly: true description: The origin of the tag. vendorName: type: string readOnly: true description: >- The name of the third-party vendor associated with the tag. operation: type: string enum: - assign - unassign description: The operation that failed. code: type: string enum: - ENTITY_NOT_FOUND - WOULD_EXCEED_MAX_TAGS - TAG_KEY_CONFLICT - TAG_OWNED_BY_THIRD_PARTY - TAG_ALREADY_IN_STATE description: >- Error code indicating the type of failure. When multiple errors occur for an entity, they are ordered by priority (most critical first): 1. `ENTITY_NOT_FOUND` - The entity does not exist (highest priority; if present, no further operations are attempted for this entity). 2. `WOULD_EXCEED_MAX_TAGS` - Assignment would exceed the maximum number of tags allowed on an endpoint. 3. `TAG_KEY_CONFLICT` - Tag key already exists with a different value on the endpoint. 4. `TAG_OWNED_BY_THIRD_PARTY` - Tag cannot be unassigned because it was not created by Sophos and is managed externally. 5. `TAG_ALREADY_IN_STATE` - Tag is already in the desired state (already assigned with same value when assigning, or already unassigned when unassigning). message: type: string description: >- Human-readable error message describing the failure. example: items: - 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11 - 28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12 errors: - entityId: 38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13 status: partial assigned: - key: Project value: Apollo unassigned: - key: Department value: Finance tagErrors: - tag: key: Country value: UK operation: assign code: TAG_KEY_CONFLICT message: Tag key 'Country' already exists with value 'USA' '400': description: Invalid request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Authentication required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT