# REST API: Users

> The 15 operations of the area Users, with parameters, bodies and responses.

Source: https://pithyx.org/docs/reference/api/users/
Markdown: https://pithyx.org/docs/reference/api/users.md

Generated from the daemon's OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on [API](https://pithyx.org/docs/developers/daemon/api/).

## GET /api/groups

Administrators only. Every group with its members, the built-in group users (every user) first.

**Responses**

- 200: `application/json`: [GroupSummary](https://pithyx.org/docs/reference/api/schemas/#groupsummary)[]

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/groups

Administrators only. Creates a group with a Linux group (a gid from 30000 to 39999 that is never given out again) and its members.

**Request body**: `application/json`: [NewGroup](https://pithyx.org/docs/reference/api/schemas/#newgroup)

**Responses**

- 201: `application/json`: [GroupSummary](https://pithyx.org/docs/reference/api/schemas/#groupsummary)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PATCH /api/groups/{groupId}

Administrators only. Renames a group, changes its description or sets its members; the gid stays. The built-in group cannot be changed.

**Parameters**

| Name      | In   | Type            | Required | Description |
| --------- | ---- | --------------- | -------- | ----------- |
| `groupId` | path | integer (int64) | yes      |             |

**Request body**: `application/json`: [GroupUpdate](https://pithyx.org/docs/reference/api/schemas/#groupupdate)

**Responses**

- 200: `application/json`: [GroupSummary](https://pithyx.org/docs/reference/api/schemas/#groupsummary)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/groups/{groupId}

Administrators only. Deletes a group and its Linux group; files keep its gid, which is never given out again. The built-in group stays.

**Parameters**

| Name      | In   | Type            | Required | Description |
| --------- | ---- | --------------- | -------- | ----------- |
| `groupId` | path | integer (int64) | yes      |             |

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## GET /api/homes

Administrators only. The home pool, every pool with whether it can take the homes, the default quota and every home with its user, space and quota, the homes of deleted users included.

**Responses**

- 200: `application/json`: [HomeOverview](https://pithyx.org/docs/reference/api/schemas/#homeoverview)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/homes/{shareId}

Administrators only. Deletes the home of a deleted user with every file and snapshot, after its folder name was typed (confirm).

**Parameters**

| Name      | In    | Type            | Required | Description |
| --------- | ----- | --------------- | -------- | ----------- |
| `shareId` | path  | integer (int64) | yes      |             |
| `confirm` | query | string          | no       |             |

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/homes/{shareId}/release

Administrators only. Moves the files of a deleted user's home into a new folder of a shared folder as a job, then deletes the home with its recycle bin.

**Parameters**

| Name      | In   | Type            | Required | Description |
| --------- | ---- | --------------- | -------- | ----------- |
| `shareId` | path | integer (int64) | yes      |             |

**Request body**: `application/json`: [HomeReleaseRequest](https://pithyx.org/docs/reference/api/schemas/#homereleaserequest)

**Responses**

- 202: `application/json`: [Job](https://pithyx.org/docs/reference/api/schemas/#job)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/homes/move

Administrators only. Moves every home to another pool as a job: each home is read-only while it is copied with its files, owners and ACLs, then it is used from the new pool and the old copy is destroyed. A home that fails stays where it was.

**Request body**: `application/json`: [HomeMoveRequest](https://pithyx.org/docs/reference/api/schemas/#homemoverequest)

**Responses**

- 202: `application/json`: [Job](https://pithyx.org/docs/reference/api/schemas/#job)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/homes/settings

Administrators only. Sets the quota of every home without its own (at least 1 MiB, null for none).

**Request body**: `application/json`: [HomeSettingsRequest](https://pithyx.org/docs/reference/api/schemas/#homesettingsrequest)

**Responses**

- 200: `application/json`: [HomeOverview](https://pithyx.org/docs/reference/api/schemas/#homeoverview)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/homes/users/{userId}/quota

Administrators only. Sets a user's own home quota: at least 1 MiB, 0 for none, null for the default.

**Parameters**

| Name     | In   | Type            | Required | Description |
| -------- | ---- | --------------- | -------- | ----------- |
| `userId` | path | integer (int64) | yes      |             |

**Request body**: `application/json`: [HomeQuotaRequest](https://pithyx.org/docs/reference/api/schemas/#homequotarequest)

**Responses**

- 200: `application/json`: [HomeOverview](https://pithyx.org/docs/reference/api/schemas/#homeoverview)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## GET /api/users

Administrators only. Every user with its Linux uid and home folder.

**Responses**

- 200: `application/json`: [UserSummary](https://pithyx.org/docs/reference/api/schemas/#usersummary)[]

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/users

Administrators only. Creates a user with a Linux and a Samba account with the password (a uid from 20000 to 29999 that is never given out again, the group users, no login shell) and its home on the home pool when there is one.

**Request body**: `application/json`: [NewUser](https://pithyx.org/docs/reference/api/schemas/#newuser)

**Responses**

- 201: `application/json`: [UserSummary](https://pithyx.org/docs/reference/api/schemas/#usersummary)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PATCH /api/users/{userId}

Administrators only. Changes the display name, the administrator right, the SMB and SFTP rights or whether the user is deactivated. Deactivating ends the user's sessions and expires the Linux account. The last active administrator keeps the right and stays active, and nobody deactivates themselves.

**Parameters**

| Name     | In   | Type            | Required | Description |
| -------- | ---- | --------------- | -------- | ----------- |
| `userId` | path | integer (int64) | yes      |             |

**Request body**: `application/json`: [UserUpdate](https://pithyx.org/docs/reference/api/schemas/#userupdate)

**Responses**

- 200: `application/json`: [UserSummary](https://pithyx.org/docs/reference/api/schemas/#usersummary)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/users/{userId}

Administrators only. Deletes the user and its Linux account; its uid is never given out again and its other files stay. Its home stays as <name>.deleted-<uid> (home=keep, the default), is deleted with every file (home=delete with confirm set to the user name) or moves into a folder of the shared folder shareId as a job (home=move), which the answer returns. Nobody deletes themselves, and the last administrator stays.

**Parameters**

| Name      | In    | Type            | Required | Description |
| --------- | ----- | --------------- | -------- | ----------- |
| `userId`  | path  | integer (int64) | yes      |             |
| `home`    | query | string          | no       |             |
| `shareId` | query | integer (int64) | no       |             |
| `confirm` | query | string          | no       |             |

**Responses**

- 200: `application/json`: [UserDeletion](https://pithyx.org/docs/reference/api/schemas/#userdeletion)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/users/{userId}/password

Administrators only. Sets a new password, for SMB and SFTP as well, and ends every session of the user.

**Parameters**

| Name     | In   | Type            | Required | Description |
| -------- | ---- | --------------- | -------- | ----------- |
| `userId` | path | integer (int64) | yes      |             |

**Request body**: `application/json`: [PasswordReset](https://pithyx.org/docs/reference/api/schemas/#passwordreset)

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).