> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labtrace.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> User management endpoints for profiles, credit balance, admin operations, and transaction history

# Users

User management endpoints handle user profiles, credit balance, admin operations, transaction history, and other user-related functionality.

## User Profile

### Get All Users

<Card title="GET /users" icon="users">
  Get all users (admin only)
</Card>

### Response

```json theme={null}
{
  "records": [
    {
      "id": "user-uuid",
      "name": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "organisation": "Research Institute",
      "location": "New York",
      "isActive": true,
      "createdOn": "2024-01-01T00:00:00Z",
      "userStatus": "Active",
      "creditBalance": 100,
      "avatar": "avatar-url"
    }
  ],
  "start": 0,
  "limit": 50,
  "totalRecords": 1
}
```

### Get User by ID

<Card title="GET /users/{userId}" icon="user">
  Get user information by ID
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "id": "user-uuid",
  "name": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "organisation": "Research Institute",
  "location": "New York",
  "isActive": true
}
```

### Get User by Email

<Card title="GET /users/email/{email}" icon="user">
  Get user information by email
</Card>

### Parameters

* `email` (path): User email address

### Response

```json theme={null}
{
  "id": "user-uuid",
  "name": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "organisation": "Research Institute",
  "location": "New York",
  "isActive": true
}
```

### Update User

<Card title="PATCH /users/{userId}" icon="edit">
  Update user information
</Card>

### Parameters

* `userId` (path): User ID

### Request Body

```json theme={null}
{
  "name": "Updated Name",
  "lastName": "Updated LastName",
  "organisation": "New Organisation",
  "location": "New Location"
}
```

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User updated"
  }
}
```

## User Avatar

### Upload Avatar

<Card title="POST /users/{userId}/avatar" icon="image">
  Upload a user avatar image
</Card>

### Parameters

* `userId` (path): User ID

### Request Body (multipart/form-data)

```
avatar: [File] - Image file for avatar
```

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User avatar added!"
  }
}
```

### Get Avatar

<Card title="GET /users/{userId}/avatar" icon="image">
  Get user avatar
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "avatar": "base64-encoded-image-data"
}
```

## User Blockchain Address

### Get User Public Key

<Card title="GET /users/{userId}/pubkey" icon="key">
  Get user's blockchain public key address
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "pubKey": "ALGORAND_PUBLIC_KEY_ADDRESS"
}
```

## Credit Balance

### Get Credit Balance

<Card title="GET /users/{userId}/credit-balance" icon="coins">
  Get user's credit balance
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "creditBalance": 150
}
```

### Update Credit Balance (Admin Only)

<Card title="POST /users/{adminId}/credit-balance/{userId}" icon="coins">
  Update user's credit balance (admin only)
</Card>

### Parameters

* `adminId` (path): Admin user ID
* `userId` (path): Target user ID

### Request Body

```json theme={null}
{
  "amount": 100,
  "operationType": "add"
}
```

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User credits correctly updated!"
  }
}
```

## Transaction History

### Download Transaction History

<Card title="GET /users/{userId}/transactions/{from}/{to}/download" icon="download">
  Download user's transaction history
</Card>

### Parameters

* `userId` (path): User ID
* `from` (path): Start date (YYYY-MM-DD format)
* `to` (path): End date (YYYY-MM-DD format)

### Response

```json theme={null}
{
  "txs": [
    {
      "id": "tx-uuid",
      "createdAt": "2024-01-15T10:30:00Z",
      "amount": -50,
      "type": "PROJECT_CREATION"
    },
    {
      "id": "tx-uuid-2",
      "createdAt": "2024-01-16T14:20:00Z",
      "amount": -10,
      "type": "PROJECT_INVITATION"
    }
  ]
}
```

## User Permissions

### Check Project Creation Permission

<Card title="GET /users/{userId}/can-create-project" icon="shield-check">
  Check if user can create projects
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User can create project"
  }
}
```

### Check Member Invitation Permission

<Card title="GET /users/{userId}/can-invite-member" icon="shield-check">
  Check if user can invite members to projects
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User can invite members"
  }
}
```

### Check Admin Status

<Card title="GET /users/{userId}/is-admin" icon="shield-check">
  Check if user has admin privileges
</Card>

### Parameters

* `userId` (path): User ID

### Response

```json theme={null}
{
  "isAdmin": true
}
```

## Admin Operations

### Suspend User

<Card title="POST /users/{adminId}/suspend/{userEmail}" icon="ban">
  Suspend a user account (admin only)
</Card>

### Parameters

* `adminId` (path): Admin user ID
* `userEmail` (path): Email of user to suspend

### Request Body

```json theme={null}
{
  "reason": "Violation of terms of service"
}
```

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User correctly suspended!"
  }
}
```

### Revoke User Suspension

<Card title="POST /users/{adminId}/revoke-suspension/{userEmail}" icon="unlock">
  Revoke user suspension (admin only)
</Card>

### Parameters

* `adminId` (path): Admin user ID
* `userEmail` (path): Email of user to unsuspend

### Response

```json theme={null}
{
  "info": {
    "statusCode": 200,
    "responseMessage": "User suspension correctly revoked!"
  }
}
```

## User Status

Users can have the following statuses:

* **Active**: User is active and can use the platform
* **On-hold**: User registration is pending activation
* **Suspended**: User account is suspended by admin

## Tags Management

### Get All Tags

<Card title="GET /tags" icon="tags">
  Get all available tags
</Card>

### Response

```json theme={null}
{
  "records": {
    "id": "tag-uuid",
    "name": "research"
  },
  "start": 0,
  "limit": 50,
  "totalRecords": 1
}
```

### Create Tag

<Card title="POST /tags" icon="plus">
  Create a new tag
</Card>

### Request Body

```json theme={null}
{
  "name": "new-tag"
}
```

### Response

```json theme={null}
{
  "info": {
    "statusCode": 201,
    "responseMessage": "Tag has been successfully added."
  }
}
```

### Search Tags

<Card title="GET /tags/search" icon="search">
  Search for tags
</Card>

### Query Parameters

* `tag` (query): Search term for tag names

### Response

```json theme={null}
{
  "records": [
    {
      "id": "tag-uuid",
      "name": "research"
    }
  ],
  "start": 0,
  "limit": 50,
  "totalRecords": 1
}
```

### Example

```bash theme={null}
curl -X GET "https://api.labtrace.io/tags/search?tag=research" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Credit System

### Credit Costs

Different operations have different credit costs:

* **Project Creation**: 50 credits
* **Project Invitation**: 10 credits
* **File Upload**: 1 credit (private files) or file size in MB (public files)
* **File Deletion**: 1 credit

### Credit Balance Management

* Users start with an initial credit balance
* Admins can add or subtract credits from user accounts
* Credits are automatically deducted for blockchain operations
* Users can view their transaction history

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": {
    "statusCode": 400,
    "message": "Invalid request parameters"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "statusCode": 401,
    "message": "Authentication required"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "error": {
    "statusCode": 403,
    "message": "Insufficient permissions"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "error": {
    "statusCode": 404,
    "message": "User not found"
  }
}
```

## User Management Best Practices

### Profile Management

* Keep user information up to date
* Use meaningful organisation and location data
* Regularly update avatars for better user experience

### Credit Management

* Monitor credit balance regularly
* Plan operations based on available credits
* Contact admin for credit refills when needed

### Security

* Use strong passwords and change them regularly
* Report suspicious activity immediately
* Keep personal information secure

### Admin Operations

* Only suspend users when necessary
* Provide clear reasons for suspensions
* Monitor user activity for policy violations
* Regularly audit user permissions and access