Groups

The groups namespace provides API methods to retrieve all or specific user groups. This page covers the following API methods:

• GET /groups

• GET /groups/{group_id}

GET /groups

Returns all groups. Requires site admin access.

This method uses pagination so you might need to request additional pages to retrieve all groups.

Request

Parameters

page integer Number of page to return (default: first page)

per_page integer Maximum number of groups to return (supported: 15, 25, 50, 100; default: 100)

expands string Comma-separated list of expands to return.

Schema

"page": {
    "type": "integer",
    "format": "int64",
    "description": "Number of page (default: first page)."
},
"per_page": {
    "type": "integer",
    "format": "int64",
    "enum": [
        15,
        25,
        50,
        100
    ],
    "description": "Maximum number of items to return per page (default: 100)."
},
"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

• users

Response

GET /api/v1/groups

200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": null,
    "last_page": 1,
    "per_page": 100,
    "total": 4,
    "result": [
        {
            "id": 1,
            "name": "QA",
            "members": [1, 2, 3, 4, 5, ..],
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null
        },
        {
            "id": 2,
            "name": "Dev",
            "members": [3, 4, 5, ..],
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null
        },
        ..
    ],
    "expands": {
        ..
    }
}

Examples

// Get first 100 groups
GET /api/v1/groups

// Get second result page (pagination)
GET /api/v1/groups?page=2

// Get groups and include user details
GET /api/v1/groups?expands=users

Status codes

200 400 401 403 422 (details)

GET /groups/{group_id}

Returns a single group. Requires site admin access.

group_id id required ID of the group to return.

Request

Parameters

expands string Comma-separated list of expands to return.

Schema

"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

• users

Request & response

GET /api/v1/groups/1

200 OK
{
    "result": {
        "id": 1,
        "name": "QA",
        "members": [1, 2, 3, 4, 5, ..],
        "created_at": "..",
        "created_by": 2,
        "updated_at": null,
        "updated_by": null
    },
    "expands": {
        ..
    }
}

Examples

// Get the group with ID 5
GET /api/v1/groups/5

// Get a group and include user details
GET /api/v1/groups/1?expands=users

Status codes

200 400 401 403 404 422 (details)