Skip to main content

​
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 -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 -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 -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": "[email protected]"
  }'

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us