> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Manage users via the REST API

## Overview

The Users API allows you to list users, retrieve user details, and manage user accounts. User management capabilities depend on your permissions within the organization or instance.

## List Users

Retrieve a list of users. The list may be filtered based on organization context and your permissions.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.cvat.ai/api/users" \
    -H "Authorization: Token <your_token>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.cvat.ai/api/users",
      headers={"Authorization": "Token <your_token>"}
  )
  users = response.json()
  ```
</CodeGroup>

### Query Parameters

<ParamField query="username" type="string">
  Filter by username
</ParamField>

<ParamField query="first_name" type="string">
  Filter by first name
</ParamField>

<ParamField query="last_name" type="string">
  Filter by last name
</ParamField>

<ParamField query="is_active" type="boolean">
  Filter by active status
</ParamField>

<ParamField query="search" type="string">
  Search users by username, first name, or last name
</ParamField>

<ParamField query="sort" type="string">
  Sort by: `username`, `first_name`, `last_name`, `id`, `is_active`
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination
</ParamField>

<ParamField query="page_size" type="integer">
  Number of results per page
</ParamField>

<ParamField query="filter" type="string">
  JSON Logic filter expression. Available fields: `username`, `first_name`, `last_name`, `id`, `is_active`
</ParamField>

<ParamField header="X-Organization" type="string">
  Organization context (shows organization members)
</ParamField>

<ParamField query="org" type="string">
  Organization slug
</ParamField>

<ParamField query="org_id" type="integer">
  Organization ID
</ParamField>

### Response

<ResponseField name="count" type="integer">
  Total number of users
</ResponseField>

<ResponseField name="next" type="string">
  URL for the next page
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page
</ResponseField>

<ResponseField name="results" type="array">
  Array of user objects

  <ResponseField name="id" type="integer">
    User ID
  </ResponseField>

  <ResponseField name="username" type="string">
    Username
  </ResponseField>

  <ResponseField name="first_name" type="string">
    First name
  </ResponseField>

  <ResponseField name="last_name" type="string">
    Last name
  </ResponseField>

  <ResponseField name="email" type="string">
    Email address
  </ResponseField>

  <ResponseField name="is_active" type="boolean">
    Whether the user account is active
  </ResponseField>

  <ResponseField name="is_staff" type="boolean">
    Whether the user has staff privileges
  </ResponseField>

  <ResponseField name="is_superuser" type="boolean">
    Whether the user has superuser privileges
  </ResponseField>

  <ResponseField name="last_login" type="string">
    Last login timestamp
  </ResponseField>

  <ResponseField name="date_joined" type="string">
    Account creation timestamp
  </ResponseField>
</ResponseField>

## Get User Details

Retrieve detailed information about a specific user.

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/users/{id}" \
  -H "Authorization: Token <your_token>"
```

### Path Parameters

<ParamField path="id" type="integer" required>
  User identifier
</ParamField>

### Response

Returns a user object with all available fields.

## Get Current User

Retrieve details of the currently authenticated user.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.cvat.ai/api/users/self" \
    -H "Authorization: Token <your_token>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.cvat.ai/api/users/self",
      headers={"Authorization": "Token <your_token>"}
  )
  user = response.json()
  print(f"Logged in as: {user['username']}")
  ```
</CodeGroup>

### Response

<ResponseField name="id" type="integer">
  User ID
</ResponseField>

<ResponseField name="username" type="string">
  Username
</ResponseField>

<ResponseField name="first_name" type="string">
  First name
</ResponseField>

<ResponseField name="last_name" type="string">
  Last name
</ResponseField>

<ResponseField name="email" type="string">
  Email address
</ResponseField>

<ResponseField name="groups" type="array">
  Array of group memberships
</ResponseField>

<ResponseField name="is_staff" type="boolean">
  Staff status
</ResponseField>

<ResponseField name="is_superuser" type="boolean">
  Superuser status
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Account active status
</ResponseField>

<ResponseField name="last_login" type="string">
  Last login timestamp
</ResponseField>

<ResponseField name="date_joined" type="string">
  Registration date
</ResponseField>

## Update a User

Update user profile information. Users can update their own profile, while administrators can update any user.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://app.cvat.ai/api/users/{id}" \
    -H "Authorization: Token <your_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      f"https://app.cvat.ai/api/users/{user_id}",
      headers={"Authorization": "Token <your_token>"},
      json={
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com"
      }
  )
  updated_user = response.json()
  ```
</CodeGroup>

### Path Parameters

<ParamField path="id" type="integer" required>
  User identifier
</ParamField>

### Request Body

<ParamField body="first_name" type="string">
  First name
</ParamField>

<ParamField body="last_name" type="string">
  Last name
</ParamField>

<ParamField body="email" type="string">
  Email address
</ParamField>

<Note>
  Some fields like `username`, `is_staff`, and `is_superuser` can only be modified by administrators.
</Note>

## Delete a User

Delete a user account. This operation typically requires administrator privileges.

```bash theme={null}
curl -X DELETE "https://app.cvat.ai/api/users/{id}" \
  -H "Authorization: Token <your_token>"
```

<Warning>
  Deleting a user will affect all resources owned by that user. This action cannot be undone.
</Warning>

### Path Parameters

<ParamField path="id" type="integer" required>
  User identifier
</ParamField>

## User Registration

Create a new user account. See the [Authentication](/api/authentication#register) page for registration details.

## Search Users

Find users by partial matching on multiple fields:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/users?search=john" \
  -H "Authorization: Token <your_token>"
```

The search parameter matches against:

* Username
* First name
* Last name

## Filter Active Users

Retrieve only active user accounts:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/users?is_active=true" \
  -H "Authorization: Token <your_token>"
```

## List Organization Members

Get users within a specific organization:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/users?org=my-team" \
  -H "Authorization: Token <your_token>"
```

Or using the organization header:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/users" \
  -H "Authorization: Token <your_token>" \
  -H "X-Organization: my-team"
```

## Example: User Management

```python theme={null}
import requests

BASE_URL = "https://app.cvat.ai/api"
HEADERS = {"Authorization": "Token <your_token>"}

# Get current user info
current_user = requests.get(
    f"{BASE_URL}/users/self",
    headers=HEADERS
).json()

print(f"Logged in as: {current_user['username']}")
print(f"Email: {current_user['email']}")
print(f"User ID: {current_user['id']}")

# Update profile
if current_user['first_name'] == "":
    updated = requests.patch(
        f"{BASE_URL}/users/{current_user['id']}",
        headers=HEADERS,
        json={
            "first_name": "John",
            "last_name": "Doe"
        }
    ).json()
    print(f"Updated name to: {updated['first_name']} {updated['last_name']}")

# Search for users
users = requests.get(
    f"{BASE_URL}/users",
    headers=HEADERS,
    params={"search": "admin", "is_active": True}
).json()

print(f"\nFound {users['count']} active users matching 'admin':")
for user in users["results"][:5]:  # Show first 5
    print(f"  - {user['username']} ({user['first_name']} {user['last_name']})")

# List users with pagination
page = 1
page_size = 10

while True:
    response = requests.get(
        f"{BASE_URL}/users",
        headers=HEADERS,
        params={"page": page, "page_size": page_size}
    ).json()
    
    for user in response["results"]:
        print(f"User: {user['username']} - {user['email']}")
    
    if not response["next"]:
        break
    page += 1
```

## Example: Find Users by Role

Find users in an organization with a specific role:

```python theme={null}
import requests

BASE_URL = "https://app.cvat.ai/api"
HEADERS = {"Authorization": "Token <your_token>"}
ORG_SLUG = "my-team"

# Get all supervisors in the organization
memberships = requests.get(
    f"{BASE_URL}/memberships",
    headers=HEADERS,
    params={"org": ORG_SLUG, "role": "supervisor"}
).json()

print(f"Supervisors in {ORG_SLUG}:")
for membership in memberships["results"]:
    user = membership["user"]
    print(f"  - {user['username']} ({user['first_name']} {user['last_name']})")

# Get detailed info for each supervisor
for membership in memberships["results"]:
    user_id = membership["user"]["id"]
    user_detail = requests.get(
        f"{BASE_URL}/users/{user_id}",
        headers=HEADERS
    ).json()
    
    print(f"\n{user_detail['username']}:")
    print(f"  Email: {user_detail['email']}")
    print(f"  Last login: {user_detail['last_login']}")
    print(f"  Member since: {user_detail['date_joined']}")
```

## User Permissions

User capabilities depend on their role:

### Regular Users

* View their own profile
* Update their own profile
* View users in their organizations
* Create projects and tasks

### Organization Maintainers

* All regular user permissions
* View all organization members
* Invite users to organization
* Assign roles to members

### Administrators

* All permissions
* Create and delete users
* Modify any user account
* Access system-wide user list
* Manage user privileges