Users

The user namespace provides a simple method to get the current, authenticated user. You can also use this method to test API access and authentication.

The users namespace provides API methods to retrieve all or specific users.

This page covers the following API methods:

• GET /projects/{project_id}/users

• GET /user

• GET /users

• GET /users/{user_id}

GET /projects/{project_id}/users

Returns all users for a project.

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

project_id id required ID of the project.

Request

Parameters

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

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

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)."
}

Response

GET /api/v1/projects/1/users

200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        { "id": 1, "name": "User 1", },
        { "id": 2, "name": "User 2", },
        ..
    ]
}

Examples

// Get first 100 users for project with ID 5
GET /api/v1/project/5/users

// Get second result page (pagination)
GET /api/v1/project/5/users?page=2

Status codes

200 400 401 404 422 (details)

GET /user

Returns the current user. A typical use case for this method is to test API access and authentication.

Response

GET /api/v1/user

200 OK
{
    "id": 1,
    "name": "User 1",
    "timezone": null,
    "date_format": null,
    "time_format": null
}

Status codes

200 400 401 (details)

GET /users

Returns all users. Requires site admin access.

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

Request

Parameters

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

per_page integer Maximum number of users 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:

• groups

• roles

• users

Response

GET /api/v1/users

200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "name": "User 1",
            "email": "[e-mail]",
            "type": 4,
            "timezone": null,
            "date_format": null,
            "time_format": null,
            ..
            "role_id": 4,
            "groups": [1, 2],
            "created_at": "..",
            "created_by": null,
            "updated_at": null,
            "updated_by": null
        },
        {
            "id": 2,
            "name": "User 2",
            "email": "[e-mail]",
            "type": 1,
            "timezone": null,
            "date_format": null,
            "time_format": null,
            ..
            "role_id": 2,
            "groups": [],
            "created_at": "..",
            "created_by": 1,
            "updated_at": null,
            "updated_by": null
        },
        ..
    ],
    "expands": {
        ..
    }
}

Examples

// Get first 100 users
GET /api/v1/users

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

// Get users and include group & role details
GET /api/v1/users?expands=groups,roles

Status codes

200 400 401 403 422 (details)

GET /users/{user_id}

Returns a single user. Requires site admin access.

user_id id required ID of the user 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:

• groups

• roles

• users

Response

GET /api/v1/users/1

200 OK
{
    {
        "id": 1,
        "name": "User 1",
        "email": "[e-mail]",
        "type": 4,
        "timezone": null,
        "date_format": null,
        "time_format": null,
        ..
        "role_id": 4,
        "groups": [1, 2],
        "created_at": "..",
        "created_by": null,
        "updated_at": null,
        "updated_by": null
    },
    "expands": {
        ..
    }
}

Examples

// Get the user with ID 5
GET /api/v1/users/5

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

Status codes

200 400 401 403 404 422 (details)