Skip to main content
Groups let you bundle users together and assign permissions to the group as a whole. Any permission you grant to a group applies to all of its members, making it easy to manage access at scale.

​
List my groups

Returns all groups the authenticated user belongs to within the current tenant. 
GET https://api-staging.knowledgestack.ai/v1/tenant-groups/my-group
Example 
curl https://api-staging.knowledgestack.ai/v1/tenant-groups/my-group \
  -H "Authorization: Bearer <your-api-key>"
Response — list of GroupResponse

​
List all groups

Returns all groups in the current tenant. 
GET https://api-staging.knowledgestack.ai/v1/tenant-groups
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenant-groups \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[GroupResponse]
​
id
string
UUID of the group.
​
tenant_id
string
UUID of the tenant this group belongs to.
​
name
string
Display name of the group.
​
description
string | null
Optional description of the group’s purpose.
​
member_count
integer | null
Number of users in the group.
​
created_at
string
ISO 8601 timestamp of group creation.
​
updated_at
string
ISO 8601 timestamp of the last update.

​
Create group

Creates a new group in the current tenant. 
POST https://api-staging.knowledgestack.ai/v1/tenant-groups
​
name
string
required
Display name for the group (1–255 characters).
​
description
string
Optional description (up to 1024 characters).
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenant-groups \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering", "description": "All engineering team members"}'
Response — GroupResponse

​
Get group

Returns details for a single group. 
GET https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}
​
group_id
string
required
UUID of the group.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-... \
  -H "Authorization: Bearer <your-api-key>"
Response — GroupResponse

​
Update group

Updates a group’s name or description. All fields are optional. 
PATCH https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}
​
group_id
string
required
UUID of the group to update.
​
name
string
New display name (1–255 characters).
​
description
string
New description.
Example 
curl -X PATCH https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-... \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering — Backend"}'
Response — GroupResponse

​
Delete group

Permanently deletes a group. Member users are not deleted, but they lose any permissions previously granted to this group. 
DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}
​
group_id
string
required
UUID of the group to delete.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-... \
  -H "Authorization: Bearer <your-api-key>"

​
List group members

Returns all users who belong to a group. 
GET https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/members
​
group_id
string
required
UUID of the group.
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../members \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[MembershipResponse]
​
id
string
UUID of the membership record.
​
tenant_id
string
UUID of the tenant.
​
group_id
string
UUID of the group.
​
user_id
string
UUID of the user.
​
created_at
string
ISO 8601 timestamp when the user was added to the group.
​
updated_at
string
ISO 8601 timestamp of the last update.

​
Add group member

Adds a user to a group. 
POST https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/members
​
group_id
string
required
UUID of the group.
​
user_id
string
required
UUID of the user to add.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../members \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "u1u2u3u4-..."}'
Response — MembershipResponse

​
Remove group member

Removes a user from a group. The user’s account is not affected. 
DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/members/{user_id}
​
group_id
string
required
UUID of the group.
​
user_id
string
required
UUID of the user to remove.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../members/u1u2u3u4-... \
  -H "Authorization: Bearer <your-api-key>"

​
List group permissions

Returns all path permissions assigned to a group. 
GET https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/permissions
​
group_id
string
required
UUID of the group.
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../permissions \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[GroupPermissionResponse]
​
id
string
UUID of the permission record.
​
tenant_id
string
UUID of the tenant.
​
group_id
string
UUID of the group this permission belongs to.
​
path_part_id
string
UUID of the path part (folder or document) this permission applies to.
​
materialized_path
string
Full path string for the resource.
​
capability
string
The level of access granted. One of READ_ONLY, READ_WRITE.
​
created_at
string
ISO 8601 timestamp when the permission was created.
​
updated_at
string
ISO 8601 timestamp of the last update.

​
Create group permission

Grants a group access to a specific path part (folder or document). 
POST https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/permissions
​
group_id
string
required
UUID of the group.
​
path_part_id
string
required
UUID of the path part to grant access to.
​
capability
string
required
Access level to grant. One of:
ValueDescription
READ_ONLYGroup members can view the resource.
READ_WRITEGroup members can view and modify the resource.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../permissions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"path_part_id": "p1p2p3p4-...", "capability": "READ_WRITE"}'
Response — GroupPermissionResponse

​
Update group permission

Updates the capability of an existing group permission. 
PATCH https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/permissions/{permission_id}
​
group_id
string
required
UUID of the group.
​
permission_id
string
required
UUID of the permission to update.
​
path_part_id
string
UUID of the new path part target.
​
capability
string
Updated capability. One of READ_ONLY, READ_WRITE.
Example 
curl -X PATCH https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../permissions/pm1pm2pm3-... \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"capability": "READ_ONLY"}'
Response — GroupPermissionResponse

​
Delete group permission

Revokes a permission from a group. 
DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/{group_id}/permissions/{permission_id}
​
group_id
string
required
UUID of the group.
​
permission_id
string
required
UUID of the permission to revoke.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tenant-groups/g1g2g3g4-.../permissions/pm1pm2pm3-... \
  -H "Authorization: Bearer <your-api-key>"