Groups

List Groups

GET /v1/groups

List groups on the current account.

Query Parameters:

pageSize (integer, optional): How many elements per page (1-100, default: 50)
pageNumber (integer, optional): Current page number (default: 1)
userDetailsMaxCount (integer, optional): Maximum number of user details to return per group (0-100, default: 0)
sortField (string, optional): Field to sort by (id, name, createdAt, description, default: createdAt)
sortDirection (string, optional): Sort direction (ASC, DESC, default: ASC)
search (string, optional): Search keyword

Response (200 OK):

{
    "content": [
        {
            "id": "12a3b4c5-d6e7-8f90-1234-567890abcdef",
            "name": "Developers",
            "description": "Development team members",
            "numberOfUsers": 5,
            "createdAt": "2024-01-01T08:00:00Z",
            "updatedAt": "2024-01-15T10:30:00Z",
            "userDetails": [
                {
                    "avatarUrl": "https://example.com/avatar1.jpg",
                    "firstName": "John",
                    "lastName": "Doe"
                },
                {
                    "avatarUrl": null,
                    "firstName": "Jane",
                    "lastName": "Smith"
                }
            ]
        },
        {
            "id": "98z7y6x5-w4v3-2u1t-0987-654321fedcba",
            "name": "QA Team",
            "description": "Quality assurance specialists",
            "numberOfUsers": 3,
            "createdAt": "2024-01-05T09:00:00Z",
            "updatedAt": "2024-01-10T14:00:00Z",
            "userDetails": []
        }
    ],
    "page": {
        "size": 2,
        "pageSize": 50,
        "pageNumber": 1,
        "totalElements": 2,
        "totalPages": 1
    }
}

Response (400 Bad Request):

{
    "message": "Invalid Paging Arguments",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727"
}

Create Group

POST /v1/groups

Create a new group.

Request Body:

{
    "name": "New Team",
    "description": "A new team for special projects",
    "userIds": [
        "56d4b940-ae51-4515-b207-f63328a66b32",
        "78f6c152-bf62-5626-c318-g74439b77c43"
    ]
}

Response (201 Created):

{
    "id": "34f5e6d7-c8b9-0a12-3456-789012345678",
    "name": "New Team",
    "description": "A new team for special projects",
    "userIds": [
        "56d4b940-ae51-4515-b207-f63328a66b32",
        "78f6c152-bf62-5626-c318-g74439b77c43"
    ],
    "userDetails": [
        {
            "id": "56d4b940-ae51-4515-b207-f63328a66b32",
            "firstName": "Joe",
            "lastName": "Test",
            "email": "[email protected]",
            "avatarUrl": "https://example.com/avatar.jpg",
            "role": "builder",
            "isInvite": false
        },
        {
            "id": "78f6c152-bf62-5626-c318-g74439b77c43",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "[email protected]",
            "avatarUrl": null,
            "role": "operator",
            "isInvite": true
        }
    ]
}

Response (422 Unprocessable Entity):

{
    "message": "The given data failed to pass validation.",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727",
    "errors": {
        "name": ["The name field is required."]
    }
}

Get Group Details

GET /v1/groups/{id}

Get the details of a group that can be sent back to update it.

Path Parameters:

id (string, required): Group UUID

Response (200 OK):

{
    "id": "12a3b4c5-d6e7-8f90-1234-567890abcdef",
    "name": "Developers",
    "description": "Development team members",
    "userIds": [
        "56d4b940-ae51-4515-b207-f63328a66b32",
        "78f6c152-bf62-5626-c318-g74439b77c43"
    ],
    "userDetails": [
        {
            "id": "56d4b940-ae51-4515-b207-f63328a66b32",
            "firstName": "Joe",
            "lastName": "Test",
            "email": "[email protected]",
            "avatarUrl": "https://example.com/avatar.jpg",
            "role": "builder",
            "isInvite": false
        },
        {
            "id": "78f6c152-bf62-5626-c318-g74439b77c43",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "[email protected]",
            "avatarUrl": null,
            "role": "operator",
            "isInvite": true
        }
    ]
}

Response (404 Not Found):

{
    "message": "Group not found",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727"
}

Update Group

PUT /v1/groups/{id}

Update a group.

Path Parameters:

id (string, required): Group UUID

Request Body:

{
    "name": "Updated Team Name",
    "description": "Updated team description",
    "userIds": [
        "56d4b940-ae51-4515-b207-f63328a66b32",
        "89g7d263-ch73-6737-d429-h85550c88d54"
    ]
}

Response (200 OK):

{
    "id": "12a3b4c5-d6e7-8f90-1234-567890abcdef",
    "name": "Updated Team Name",
    "description": "Updated team description",
    "userIds": [
        "56d4b940-ae51-4515-b207-f63328a66b32",
        "89g7d263-ch73-6737-d429-h85550c88d54"
    ],
    "userDetails": [
        {
            "id": "56d4b940-ae51-4515-b207-f63328a66b32",
            "firstName": "Joe",
            "lastName": "Test",
            "email": "[email protected]",
            "avatarUrl": "https://example.com/avatar.jpg",
            "role": "builder",
            "isInvite": false
        },
        {
            "id": "89g7d263-ch73-6737-d429-h85550c88d54",
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "avatarUrl": null,
            "role": "builder",
            "isInvite": true
        }
    ]
}

Response (422 Unprocessable Entity):

{
    "message": "The given data failed to pass validation.",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727",
    "errors": {
        "name": ["The name field is required."]
    }
}

Remove Group

DELETE /v1/groups/{id}

Remove a group.

Path Parameters:

id (string, required): Group UUID

Response (204 No Content):

No response body.

Response (404 Not Found):

{
    "message": "Group was not found",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727"
}

List Group Project Memberships

GET /v1/groups/{id}/project-memberships

List project memberships on the group.

Path Parameters:

id (string, required): Group UUID

Query Parameters:

pageSize (integer, optional): How many elements per page (1-100, default: 50)
pageNumber (integer, optional): Current page number (default: 1)

Response (200 OK):

{
    "content": [
        "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "z9y8x7w6-v5u4-3210-9876-543210fedcba"
    ],
    "page": {
        "size": 2,
        "pageSize": 50,
        "pageNumber": 1,
        "totalElements": 2,
        "totalPages": 1
    }
}

Response (400 Bad Request):

{
    "message": "Invalid Paging Arguments",
    "traceId": "09f9aa68-4d89-465b-8d6d-41490fff7727"
}