Skip to content

Add new group

POST/endpoint-groups

Endpoint API · Endpoint Groups Management

Add new endpoint group to the directory.

Required permissionendpoint-groups:create

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
fields query array of string No The fields to return in a partial response.

Request body

Content type: application/json

Request body fields

namestringrequired
Group name.
Must match the pattern ^[^#,+"\\<>;]+$. Must be 1–250 characters long.
descriptionstring
Group description.
Must match the pattern ^[^#,+"\\<>;]+$. Must be at most 1000 characters long.
typestring (enum)required
Endpoint group types.
Must be one of: computer, server.
endpointIdsarray of string (uuid)
Endpoints in the group.
Must contain at most 1000 items. Items must be unique.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"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\"
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   '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']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "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"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups" -Headers $headers -Body $body -ContentType "application/json"


package main

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

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups", strings.NewReader(`{
  "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"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

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

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


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "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"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Endpoint group created.

Response fields

idstring (uuid)required
Group ID.
namestringrequired
Group name.
Must match the pattern ^[^#,+"\\<>;]+$.
descriptionstring
Group description.
Must match the pattern ^[^#,+"\\<>;]+$.
typestring (enum)required
Endpoint group types.
Must be one of: computer, server.
endpointsobject
Associated endpoints.
Show child attributesHide child attributes
totalinteger
Total number of endpoints in this group.
itemsCountinteger
Total number of items in the list.
itemsarray of object
Items must be unique.
Reference to an endpoint.
Show child attributesHide child attributes
idstring (uuid)required
Unique endpoint ID.
hostnamestring
Endpoint hostname.
tenantobjectrequired
Reference to a tenant.
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID.
createdAtstring (date-time)
When the group was created.
updatedAtstring (date-time)
When the group was last updated.

Errors

Status Meaning
404 At least one endpoint in the request not found.
409 Group names must be unique. You also can't use this API to add endpoints to a group synced from Active Directory.
500 Internal server error.

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

Response examples

201

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "description": "string",
  "type": "computer",
  "endpoints": {
    "total": 0,
    "itemsCount": 0,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "hostname": "string"
      }
    ]
  },
  "tenant": {
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "createdAt": "2026-07-28T00:00:00Z",
  "updatedAt": "2026-07-28T00:00:00Z"
}

See the guide for a narrative walkthrough of this API.