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.

cURL

curl -X GET "https://app.cvat.ai/api/users" \
  -H "Authorization: Token <your_token>"

Query Parameters

username · string

Filter by username

first_name · string

Filter by first name

last_name · string

Filter by last name

is_active · boolean

Filter by active status

search · string

Search users by username, first name, or last name

sort · string

Sort by: username, first_name, last_name, id, is_active

page · integer

Page number for pagination

page_size · integer

Number of results per page

filter · string

JSON Logic filter expression. Available fields: username, first_name, last_name, id, is_active

X-Organization · string

Organization context (shows organization members)

org · string

Organization slug

org_id · integer

Organization ID

Response

count · integer

Total number of users

next · string

URL for the next page

previous · string

URL for the previous page

results · array

Array of user objects

id · integer

User ID

username · string

Username

first_name · string

First name

last_name · string

Last name

email · string

Email address

is_active · boolean

Whether the user account is active

is_staff · boolean

Whether the user has staff privileges

is_superuser · boolean

Whether the user has superuser privileges

last_login · string

Last login timestamp

date_joined · string

Account creation timestamp

Get User Details

Retrieve detailed information about a specific user.

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

Path Parameters

id · integer · required

User identifier

Response

Returns a user object with all available fields.

Get Current User

Retrieve details of the currently authenticated user.

cURL

curl -X GET "https://app.cvat.ai/api/users/self" \
  -H "Authorization: Token <your_token>"

Response

id · integer

User ID

username · string

Username

first_name · string

First name

last_name · string

Last name

email · string

Email address

groups · array

Array of group memberships

is_staff · boolean

Staff status

is_superuser · boolean

Superuser status

is_active · boolean

Account active status

last_login · string

Last login timestamp

date_joined · string

Registration date

Update a User

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

cURL

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": "[e-mail]"
  }'

Path Parameters

id · integer · required

User identifier

Request Body

first_name · string

First name

last_name · string

Last name

email · string

Email address

Some fields like username, is_staff, and is_superuser can only be modified by administrators.

Delete a User

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

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

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

Path Parameters

id · integer · required

User identifier

User Registration

Create a new user account. See the Authentication page for registration details.

Search Users

Find users by partial matching on multiple fields:

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:

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:

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

Or using the organization header:

curl -X GET "https://app.cvat.ai/api/users" \
  -H "Authorization: Token <your_token>" \
  -H "X-Organization: my-team"

Example: User Management

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:

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