Host groups
Host groups is the Falcon Host Group collection for this CID. Paths are
under /devices/…. Dynamic groups and assignment_rule are not
implemented. group_type is always static.
This collection is not CrowdStrike production. It does not call Falcon cloud.
RPC field notes: HostGroupsService. REST schemas: API reference. Filter syntax: FQL.
These curls use Host: crowdstrike-api.localhost against Compose
Traefik on :8088. If the hostname already resolves to Traefik, you can
omit the Host header and call http://crowdstrike-api.localhost instead.
Auth
Every call needs a console session or a Bearer token:
- Cookie
cs_consolefromCreateSession(POST /identity/entities/sessions/v1) Authorization: Bearerwithhost-groups:readfor query, get, and membershost-groups:writefor create, patch, delete, and actions
A session cookie bypasses OAuth scopes. Seed client cs-local-hosts
(hosts:read only) cannot query host groups (403). There is no seeded
client with host-groups:read — use the console cookie, or a client you
created with that scope.
HTTP paths
| Method | Path | Use |
|---|---|---|
GET | /devices/queries/host-groups/v1 | Query ids. Query: filter, limit, offset, sort (name.asc / name.desc). Empty filter returns all ids. |
GET | /devices/entities/host-groups/v1?ids= | Get groups. Missing id → 200 with only found resources. |
POST | /devices/entities/host-groups/v1 | Create. Body { "name", "description" }. Empty name → 400. Success 201. |
PATCH | /devices/entities/host-groups/v1 | Update. Body { "id", "name", "description" }. |
DELETE | /devices/entities/host-groups/v1?ids= | Delete groups. |
GET | /devices/queries/host-group-members/v1?id= | Member device_ids for one group. |
POST | /devices/entities/host-group-actions/v1?action_name= | add-hosts or remove-hosts. Body { "ids": ["hg-linux"], "host_ids": ["aid-lin-02"] }. Other action_name → 400. Unknown host → 400. Duplicate add is 200 (no-op). |
Allowed FQL properties: name. Unknown property or invalid filter → 400.
Group JSON: id, name, description, group_type.
Seed groups
id | name | description | members |
|---|---|---|---|
hg-windows | Windows servers | Windows endpoints in this CID | aid-win-01, aid-win-02 |
hg-linux | Linux apps | Linux endpoints in this CID | aid-lin-01 |
Session cookie
curl -sS -c cookies.txt -H 'Host: crowdstrike-api.localhost' \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"FalconLocal!1","cloud":"us-1"}' \
http://127.0.0.1:8088/identity/entities/sessions/v1
Query host groups (cookie)
Empty filter returns at least the two seed ids, including hg-windows.
name:'win*' returns only Windows servers:
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/devices/queries/host-groups/v1?filter=name:%27win*%27&sort=name.asc'
Invalid FQL is 400:
curl -sS -o /dev/null -w '%{http_code}\n' \
-H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/devices/queries/host-groups/v1?filter=not-fql'
Get host groups (cookie)
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/devices/entities/host-groups/v1?ids=hg-windows,hg-linux'
Create (cookie)
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"name":"Ad-hoc lab","description":"Temporary lab hosts"}' \
http://127.0.0.1:8088/devices/entities/host-groups/v1
Success is 201. The new id is in resources. Empty name → 400.
Patch (cookie)
curl -sS -X PATCH -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"id":"hg-linux","name":"Linux apps","description":"Linux endpoints in this CID"}' \
http://127.0.0.1:8088/devices/entities/host-groups/v1
Delete (cookie)
curl -sS -X DELETE -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/devices/entities/host-groups/v1?ids=<group-id>'
Members (cookie)
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/devices/queries/host-group-members/v1?id=hg-linux'
Add and remove hosts (cookie)
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"ids":["hg-linux"],"host_ids":["aid-lin-02"]}' \
'http://127.0.0.1:8088/devices/entities/host-group-actions/v1?action_name=add-hosts'
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"ids":["hg-linux"],"host_ids":["aid-lin-02"]}' \
'http://127.0.0.1:8088/devices/entities/host-group-actions/v1?action_name=remove-hosts'
Create, patch, delete, and actions need host-groups:write (or a session).
A token with only host-groups:read → 403 on those methods.
Query (Bearer)
TOKEN='<access_token from a client with host-groups:read>'
curl -sS -H 'Host: crowdstrike-api.localhost' \
-H "Authorization: Bearer ${TOKEN}" \
'http://127.0.0.1:8088/devices/queries/host-groups/v1'
host-groups:read → 200. A token without that scope (including
hosts:read only) → 403. Missing or revoked token → 401.
OAuth2 mint/revoke: OAuth2. Accessible scopes: API clients.