Groups
A group gives its grants to every member in it; list, create, rename and delete groups and set who is in them.
- GET
List groups/workspaces /{workspace_id} /groups - GET
Read a group/workspaces /{workspace_id} /groups /{id} - POST
Create a group/workspaces /{workspace_id} /groups - PATCH
Rename a group/workspaces /{workspace_id} /groups /{id} - PUT
Set a group's members/workspaces /{workspace_id} /groups /{id} /members - DELETE
Delete a group/workspaces /{workspace_id} /groups /{id}
Group object
A group is a set of members who all hold the group's grants.
iduuidThe group's id.
namestringThe group's name.
created_at date-timeWhen the group was created.
updated_at date-timeWhen the group last changed.
grantsarray of GrantThe group's grants you are shown.
other_grants booleanTrue when the group holds a grant you are not shown.
member_count integerHow many members are in the group.
membersarray of GroupMemberEveryone in the group, name and email only, as read-group shows them: sent only when fields names it, then a list, empty for a group with no members.
List groups
/workspaces/{workspace_id}/groups Returns the workspace's groups, each with its grants and how many members it has, a page at a time, oldest first. Needs group.read; you see the groups your reach contains.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "groups": [ { "id": "9a0b0000-0000-4000-8000-000000000401", "name": "Helpdesk Tier 1", "created_at": "2026-11-02T10:00:00Z", "updated_at": "2026-11-02T10:00:00Z", "grants": [ { "id": "6a170000-0000-4000-8000-000000000503", "role_id": "analyst_no_raw_logs", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ], "inherited": false, "other_orgs": false } } ], "other_grants": false, "member_count": 1 }, { "id": "9a0b0000-0000-4000-8000-000000000402", "name": "Project Engineers", "created_at": "2026-11-02T10:00:00Z", "updated_at": "2026-11-02T10:00:00Z", "grants": [ { "id": "6a170000-0000-4000-8000-000000000505", "role_id": "engineer", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000103" ], "inherited": false, "other_orgs": false } } ], "other_grants": false, "member_count": 0 } ], "message": "workspace groups retrieved", "next_cursor": null}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
admin:readadmin:write - Privilege
group.read
Needs group.read. group.read applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.
Behavior
- Retry
- Safe to send again
- Paging
- Cursor · 1000 a page by default, up to 5000
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
namestringOnly the group of this name: the way to find the group a refused create names as taken. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
limitintegerHow many groups a page holds: 1 to 5000, 1000 by default.
cursorstringThe next_cursor of the previous page, with the same filters.
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idnamecreated_atupdated_atgrantsother_grantsmember_count
Sent only when named in fields: members
Response 200
The groups on this page.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor for the next page.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.NoAPP_API_ERR_BAD_PARAMETERS limit is not 1 to 5000, or cursor cannot be read or was sent with other filters.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.read. The same refusal comes when the path names a workspace other than the token's own.NoPlus the errors every call can return.
Related
Read a group
/workspaces/{workspace_id}/groups/{id} Returns one group with everyone in it, whatever your reach, so the membership read can be sent back whole. Needs group.read. A group you cannot see returns 404, as one that does not exist does.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "workspace group retrieved", "group": { "id": "9a0b0000-0000-4000-8000-000000000401", "name": "Helpdesk Tier 1", "created_at": "2026-11-02T10:00:00Z", "updated_at": "2026-11-02T10:00:00Z", "grants": [ { "id": "6a170000-0000-4000-8000-000000000503", "role_id": "analyst_no_raw_logs", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ], "inherited": false, "other_orgs": false } } ], "other_grants": false, "member_count": 1, "members": [ { "user_id": "SamChenExampleUserId00000002", "email": "sam.chen@example.com", "full_name": "Sam Chen", "display_name": "Sam" } ] }}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
admin:readadmin:write - Privilege
group.read
Needs group.read. group.read applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe group's id.
Response 200
groupGroupDetailrequiredThe group.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.read. The same refusal comes when the path names a workspace other than the token's own.No404APP_API_ERR_RECORD_NOT_FOUND No such group, or one you cannot see.NoPlus the errors every call can return.
Related
Create a group
/workspaces/{workspace_id}/groups Creates a group with its grants and, optionally, its members. Needs group.write, and grant.write over each grant it names; a group with no grants needs group.write over every organization. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 15 minutes.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "grants": [ { "role_id": "analyst_no_raw_logs", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ] } } ], "name": "Helpdesk Tier 1", "user_ids": [ "SamChenExampleUserId00000002" ] }'$body = @{ grants = @( @{ role_id = "analyst_no_raw_logs" scope = @{ kind = "selected" org_ids = @( "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ) } } ) name = "Helpdesk Tier 1" user_ids = @( "SamChenExampleUserId00000002" )}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "grants": [ { "role_id": "analyst_no_raw_logs", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105", ], }, }, ], "name": "Helpdesk Tier 1", "user_ids": [ "SamChenExampleUserId00000002", ], },)response.raise_for_status(){ "message": "group created", "id": "9a0b0000-0000-4000-8000-000000000401", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
group.write
Needs group.write. group.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Read before sending again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
Request body
namestringrequiredThe group's name. Cleaned, as every name is. Required.
grantsarray of GrantRequest or nullThe group's grants. A group with none needs group.write over every organization.
user_ids array of string or nullMembers to put in the group, each one you are shown.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_BAD_PARAMETERS name is empty, a member in user_ids is not one you can see, or a grant names a role the workspace does not have, or a malformed scope.NoAPP_API_ERR_MISSING_PARAMETER A grant names no role.NoAPP_API_ERR_PARAMETER_TOO_LONG name is longer than 128 characters.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeA grant reaches beyond what you may grant, or the group has no grants and you do not hold group.write over every organization. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No409APP_API_ERR_ALREADY_TAKEN Another group in the workspace has this name; parameter is name.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Rename a group
/workspaces/{workspace_id}/groups/{id} Renames a group. Needs group.write over it. A group you cannot see returns 404, as one that does not exist does.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Field Engineers" }'$body = @{ name = "Field Engineers"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.patch( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Field Engineers", },)response.raise_for_status(){ "message": "group renamed", "id": "9a0b0000-0000-4000-8000-000000000402"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
group.write
Needs group.write. group.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe group's id.
Request body
namestringrequiredThe new name. Cleaned, as every name is. Required.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_BAD_PARAMETERS name is empty.NoAPP_API_ERR_PARAMETER_TOO_LONG name is longer than 128 characters.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe group holds grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND No such group, or one you cannot see.No409APP_API_ERR_ALREADY_TAKEN Another group in the workspace has this name; parameter is name.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Set a group's members
/workspaces/{workspace_id}/groups/{id}/members Sets who is in a group: the list sent is the whole membership, so a member left out is removed. A member added must be one your member list shows. Needs group.write, and the group must sit inside your own access: for each of its grants, grant.write, group.write and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 APP_API_ERR_BEYOND_OWN_AUTHORITY, even when the list sent changes nothing. other_grants and the scope markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404. Sending the members it already has changes nothing. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 15 minutes.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PUT \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "user_ids": [ "SamChenExampleUserId00000002", "AlexRiveraExampleUserId00001" ] }'$body = @{ user_ids = @( "SamChenExampleUserId00000002", "AlexRiveraExampleUserId00001" )}Invoke-RestMethod -Method Put ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.put( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "user_ids": [ "SamChenExampleUserId00000002", "AlexRiveraExampleUserId00001", ], },)response.raise_for_status(){ "message": "group members replaced", "id": "9a0b0000-0000-4000-8000-000000000401", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
group.write
Needs group.write. group.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe group's id.
Request body
user_ids array of stringrequiredEveryone who is in the group from now on; an empty list empties it. Required.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_MISSING_PARAMETER user_ids is left out, null or not a list of strings.NoAPP_API_ERR_BAD_PARAMETERS A member added is not one you can see.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeYou do not hold grant.write, group.write and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs group.write over every organization. A list that changes nothing is refused the same way. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND No such group, or one you cannot see.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Delete a group
/workspaces/{workspace_id}/groups/{id} Deletes a group and its grants; its members lose what they held through it. Needs group.write, and the group must sit inside your own access: for each of its grants, grant.write, group.write and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 APP_API_ERR_BEYOND_OWN_AUTHORITY. other_grants and the scope markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404, and so does a repeat once the group is gone: treat that as done. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 15 minutes.
- Request
- Response
- curl
- PowerShell
- Python
curl -X DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "group deleted", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
group.write
Needs group.write. group.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe group's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The request carries a body other than nothing, null or {}: a delete takes none, and its options are query parameters; parameter names the body's first field, or body.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeYou do not hold grant.write, group.write and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs group.write over every organization. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND No such group, or one you cannot see.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.