Skip to main content

​
Overview

Collaborators are users or teams who have been granted access to a project. Each collaborator has a specific role that defines their permissions.

​
List Collaborators

curl -X GET "https://app.qfield.cloud/api/v1/collaborators/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/collaborators/{projectid}/ Get all collaborators for a given project.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project

​
Query Parameters

​
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 collaborators
​
next
string
URL to the next page of results
​
previous
string
URL to the previous page of results
​
results
array
Array of collaborator objects
​
project_id
uuid
ID of the project
​
collaborator
string
Username of the collaborator (person or team)
​
role
string
Collaborator role: reader, reporter, editor, manager, or admin
​
created_by
string
Username of the user who added this collaborator
​
updated_by
string
Username of the user who last updated this collaborator
​
created_at
datetime
When the collaborator was added
​
updated_at
datetime
When the collaborator was last updated
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "collaborator": "jane_smith",
      "role": "editor",
      "created_by": "john_doe",
      "updated_by": "john_doe",
      "created_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-02-15T10:00:00Z"
    },
    {
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "collaborator": "@acme_org/field_team",
      "role": "reporter",
      "created_by": "john_doe",
      "updated_by": "john_doe",
      "created_at": "2026-02-20T14:30:00Z",
      "updated_at": "2026-02-20T14:30:00Z"
    }
  ]
}

​
Add Collaborator

curl -X POST "https://app.qfield.cloud/api/v1/collaborators/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collaborator": "jane_smith",
    "role": "editor"
  }'
POST /api/v1/collaborators/{projectid}/ Add a user or team as a collaborator to the project.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project

​
Request Body

​
collaborator
string
required
Username of the person or team to add. For teams, use the format @organization/team_name
​
role
string
required
Role to assign: reader, reporter, editor, manager, or admin

​
Response

Returns the created collaborator object. 
{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "collaborator": "jane_smith",
  "role": "editor",
  "created_by": "john_doe",
  "updated_by": "john_doe",
  "created_at": "2026-03-04T12:00:00Z",
  "updated_at": "2026-03-04T12:00:00Z"
}

​
Error Responses

{
  "collaborator": ["Invalid username"]
}

​
Get Collaborator

curl -X GET "https://app.qfield.cloud/api/v1/collaborators/{projectid}/{username}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/collaborators/{projectid}/{username}/ Get the role of a specific collaborator.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project
​
username
string
required
Username of the collaborator

​
Response

Returns a single collaborator object. 
{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "collaborator": "jane_smith",
  "role": "editor",
  "created_by": "john_doe",
  "updated_by": "john_doe",
  "created_at": "2026-02-15T10:00:00Z",
  "updated_at": "2026-02-15T10:00:00Z"
}

​
Update Collaborator

curl -X PATCH "https://app.qfield.cloud/api/v1/collaborators/{projectid}/{username}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "manager"
  }'
PATCH /api/v1/collaborators/{projectid}/{username}/ Update a collaborator’s role. You can also use PUT for a full update.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project
​
username
string
required
Username of the collaborator

​
Request Body

​
role
string
required
New role: reader, reporter, editor, manager, or admin

​
Response

Returns the updated collaborator object. 
{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "collaborator": "jane_smith",
  "role": "manager",
  "created_by": "john_doe",
  "updated_by": "john_doe",
  "created_at": "2026-02-15T10:00:00Z",
  "updated_at": "2026-03-04T12:00:00Z"
}

​
Remove Collaborator

curl -X DELETE "https://app.qfield.cloud/api/v1/collaborators/{projectid}/{username}/" \
  -H "Authorization: Token YOUR_TOKEN"
DELETE /api/v1/collaborators/{projectid}/{username}/ Remove a collaborator from the project.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project
​
username
string
required
Username of the collaborator to remove

​
Response

Returns HTTP 204 No Content on success.

​
Collaborator Roles

Collaborators can have the following roles, each with different permissions:

​
Reader

  • View project data
  • Download files
  • View deltas and jobs

​
Reporter

  • All Reader permissions
  • Upload deltas (submit field changes)
  • Create delta apply jobs

​
Editor

  • All Reporter permissions
  • Upload and modify files
  • Delete files
  • Create package jobs

​
Manager

  • All Editor permissions
  • Add/remove collaborators
  • Update collaborator roles (except admin)
  • Modify project settings

​
Admin

  • All Manager permissions
  • Delete the project
  • Transfer project ownership
  • Grant admin role to other collaborators

Build docs developers (and LLMs) love

Get started for freeTalk to us