Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opengisch/qfieldcloud/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Users represent individual accounts in QFieldCloud. User endpoints allow you to search for users, view user profiles, and update your own account information.

​
List Users

curl -X GET "https://app.qfield.cloud/api/v1/users/?q=john" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/users/ Search for users and organizations.

​
Query Parameters

​
q
string
Search query to find users by username or email
​
project
uuid
Filter users by project membership
​
organization
string
Filter users by organization membership
​
exclude_organizations
integer
Exclude organizations from results. Set to 1 to exclude. Default: 0
​
exclude_teams
integer
Exclude teams from results. Set to 1 to exclude. Default: 0
​
invert
integer
Invert the project/organization filter (exclude matching users). Set to 1 to invert. Default: 0
​
limit
integer
Number of results to return per page
​
offset
integer
The initial index from which to return the results

​
Response

​
count
integer
Total number of users
​
next
string
URL to the next page of results
​
previous
string
URL to the previous page of results
​
results
array
Array of user objects
​
username
string
User’s unique username
​
type
string
User type: person, organization, or team
​
full_name
string
User’s full name
​
avatar_url
string
URL to the user’s avatar image
​
username_display
string
Display name (for teams, shows name without organization prefix)
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "username": "john_doe",
      "type": "person",
      "full_name": "John Doe",
      "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/john_doe/avatar.jpg",
      "username_display": "john_doe"
    },
    {
      "username": "acme_org",
      "type": "organization",
      "full_name": "ACME Organization",
      "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/acme_org/avatar.png",
      "username_display": "acme_org"
    },
    {
      "username": "@acme_org/field_team",
      "type": "team",
      "full_name": "Field Team",
      "avatar_url": null,
      "username_display": "field_team"
    }
  ]
}

​
Get User

curl -X GET "https://app.qfield.cloud/api/v1/users/{username}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/users/{username}/ Retrieve public information about a user, or complete information if you’re viewing your own profile.

​
Path Parameters

​
username
string
required
The username to retrieve

​
Response (Own Profile)

When retrieving your own profile, you get complete information:
​
username
string
Your username
​
type
string
User type: person
​
full_name
string
Your full name
​
email
string
Your email address
​
avatar_url
string
URL to your avatar image
​
first_name
string
Your first name
​
last_name
string
Your last name
{
  "username": "john_doe",
  "type": "person",
  "full_name": "John Doe",
  "email": "john.doe@example.com",
  "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/john_doe/avatar.jpg",
  "first_name": "John",
  "last_name": "Doe"
}

​
Response (Other User’s Profile)

When retrieving another user’s profile, you get public information only:
​
username
string
User’s username
​
type
string
User type: person, organization, or team
​
full_name
string
User’s full name
​
avatar_url
string
URL to the user’s avatar image
​
username_display
string
Display name
{
  "username": "jane_smith",
  "type": "person",
  "full_name": "Jane Smith",
  "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/jane_smith/avatar.jpg",
  "username_display": "jane_smith"
}

​
Response (Organization)

When the username refers to an organization, the response includes organization-specific fields: 
{
  "username": "acme_org",
  "type": "organization",
  "email": "info@acme.com",
  "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/acme_org/avatar.png",
  "members": ["john_doe", "jane_smith"],
  "organization_owner": "john_doe",
  "membership_role": "admin",
  "membership_role_origin": "owner",
  "membership_is_public": true,
  "teams": ["field_team", "admin_team"]
}

​
Update User

curl -X PATCH "https://app.qfield.cloud/api/v1/users/{username}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }'
PATCH /api/v1/users/{username}/ Update your own user profile. You can also use PUT for a full update.
You can only update your own profile. Attempting to update another user’s profile will result in a permission error.

​
Path Parameters

​
username
string
required
Your username

​
Request Body

All fields are optional for PATCH requests.
​
first_name
string
Your first name
​
last_name
string
Your last name
​
email
string
Your email address

​
Response

Returns the updated user object. 
{
  "username": "john_doe",
  "type": "person",
  "full_name": "John Doe",
  "email": "john.doe@example.com",
  "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/john_doe/avatar.jpg",
  "first_name": "John",
  "last_name": "Doe"
}

​
Get User’s Organizations

curl -X GET "https://app.qfield.cloud/api/v1/users/{username}/organizations/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/users/{username}/organizations/ Get all organizations that the user is a member of.
This endpoint only works when querying your own organizations. You cannot query another user’s organizations.

​
Path Parameters

​
username
string
required
Your username (must match the authenticated user)

​
Response

Returns an array of organization objects. 
[
  {
    "username": "acme_org",
    "type": "organization",
    "email": "info@acme.com",
    "avatar_url": "https://app.qfield.cloud/api/v1/files/avatars/acme_org/avatar.png",
    "members": ["john_doe", "jane_smith"],
    "organization_owner": "john_doe",
    "membership_role": "admin",
    "membership_role_origin": "owner",
    "membership_is_public": true,
    "teams": ["field_team", "admin_team"]
  }
]

​
User Types

QFieldCloud has three types of users:

​
Person

Regular individual user accounts with:
  • Personal projects
  • Organization memberships
  • Team memberships
  • Individual storage quota

​
Organization

Collective accounts that:
  • Own shared projects
  • Have multiple members
  • Can create teams
  • Have shared storage quota
  • Are managed by an organization owner

​
Team

Groups within organizations that:
  • Contain organization members
  • Can be added as project collaborators
  • Inherit from their organization
  • Use the format @organization/team_name

​
Search Examples

​
Find Users by Name

curl -X GET "https://app.qfield.cloud/api/v1/users/?q=john" \
  -H "Authorization: Token YOUR_TOKEN"

​
Find Only People (Exclude Organizations)

curl -X GET "https://app.qfield.cloud/api/v1/users/?q=smith&exclude_organizations=1" \
  -H "Authorization: Token YOUR_TOKEN"

​
Find Users in a Specific Project

curl -X GET "https://app.qfield.cloud/api/v1/users/?project=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Token YOUR_TOKEN"

​
Find Users NOT in a Project

curl -X GET "https://app.qfield.cloud/api/v1/users/?project=550e8400-e29b-41d4-a716-446655440000&invert=1" \
  -H "Authorization: Token YOUR_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us