Groups API

The Groups API lets you manage groups (folders) within workspaces.

List Groups

Get all groups in a workspace.

GET /api/group

Query Parameters

Parameter	Type	Description
`workspaceId`	string	Filter by workspace (uses default if not provided)
`parentId`	string	Filter by parent group (optional)
`search`	string	Search in group names (optional)
`sort`	string	Sort field and direction, e.g. `name:asc` or `name:desc`
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 50, max: 100)

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Projects",
      "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
      "userId": "880e8400-e29b-41d4-a716-446655440003",
      "parentId": null,
      "icon": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Active",
      "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
      "userId": "880e8400-e29b-41d4-a716-446655440003",
      "parentId": "550e8400-e29b-41d4-a716-446655440000",
      "icon": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "totalPages": 1
  },
  "count": 2,
  "filters": {
    "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
    "parentId": null,
    "search": null
  }
}

Example

curl -X GET "https://sidvy.com/api/group?workspaceId=660e8400..." \
  -H "Authorization: Bearer sidvy_abc123..."

Create Group

Create a new group.

POST /api/group

Request Body

{
  "name": "New Group",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "parentId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`name`	string	Yes	Group name
`workspaceId`	string	No	Target workspace (uses default if not provided)
`parentId`	string	No	Parent group ID (for nesting)

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "New Group",
    "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "parentId": "550e8400-e29b-41d4-a716-446655440000",
    "icon": null
  },
  "count": 1
}

Example

curl -X POST "https://sidvy.com/api/group" \
  -H "Authorization: Bearer sidvy_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "New Group", "workspaceId": "660e8400..."}'

Update Group

Update a group’s name or move it in the hierarchy.

PUT /api/group

Request Body

{
  "groupId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Renamed Group",
  "parentId": null
}

Field	Type	Required	Description
`groupId`	string	Yes	Group ID to update
`name`	string	No	New group name
`parentId`	string	No	New parent group (set to `null` to move to workspace root)

Response

Returns the updated group object in the same format as create.

Example

curl -X PUT "https://sidvy.com/api/group" \
  -H "Authorization: Bearer sidvy_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"groupId": "550e8400...", "name": "Renamed Group"}'

Delete Group

Delete a group and its contents.

DELETE /api/group

Request Body

{
  "groupId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`groupId`	string	Yes	Group ID to delete

Response

{
  "data": {
    "deleted": true,
    "groupId": "550e8400-e29b-41d4-a716-446655440000",
    "deletedChildGroups": 2
  },
  "count": 1
}

Example

curl -X DELETE "https://sidvy.com/api/group" \
  -H "Authorization: Bearer sidvy_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"groupId": "550e8400-e29b-41d4-a716-446655440000"}'

Errors

404 Not Found

{
  "error": "NOT_FOUND",
  "message": "Group not found"
}

404 Parent Not Found

{
  "error": "NOT_FOUND",
  "message": "Parent group not found"
}

400 Circular Reference

{
  "error": "VALIDATION_ERROR",
  "message": "Group cannot be its own parent"
}

400 Validation Error

{
  "error": "VALIDATION_ERROR",
  "message": "name: Required field is missing"
}