Projects

Overview

Projects are the core containers for your geospatial data in QFieldCloud. Each project contains files, deltas, jobs, and collaborators.

List Projects

curl -X GET "https://app.qfield.cloud/api/v1/projects/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/v1/projects/ List all projects owned by the authenticated user or that the user has explicit permission to access.

Query Parameters

include_public

boolean

Include public projects in the results. By default, public projects are excluded from the list.

string

Search by owner username or project name

ordering

string

Order results by: owner, name, or created_at. Prefix with - for descending order (e.g., -created_at)

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 projects

string

URL to the next page of results

string

URL to the previous page of results

results

array

Array of project objects

uuid

Unique project identifier

name

string

Project name

owner

string

Username of the project owner (person or organization)

description

string

Project description

is_public

boolean

Whether the project is publicly accessible

private

boolean

deprecated

Inverse of is_public. Deprecated, use is_public instead

created_at

datetime

When the project was created

updated_at

datetime

When the project was last updated

data_last_packaged_at

datetime

When the project data was last packaged

data_last_updated_at

datetime

When the project data was last updated

restricted_data_last_updated_at

datetime

When restricted project data was last updated

can_repackage

boolean

Whether the project can be repackaged

needs_repackaging

boolean

Whether the project needs repackaging

status

string

Project status: ok, busy, or failed

user_role

string

Current user’s role on this project: reader, reporter, editor, manager, or admin

user_role_origin

string

Origin of the user’s role: public, direct, organization, or team

shared_datasets_project_id

uuid

ID of the associated shared datasets project, if any

is_shared_datasets_project

boolean

Whether this is a shared datasets project

is_featured

boolean

Whether the project is featured

is_attachment_download_on_demand

boolean

Whether attachments are downloaded on demand

file_storage_bytes

integer

Total file storage used in bytes

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Tree Survey",
      "owner": "john_doe",
      "description": "Urban tree inventory project",
      "is_public": false,
      "private": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-03-01T14:20:00Z",
      "data_last_packaged_at": "2025-03-01T14:15:00Z",
      "data_last_updated_at": "2025-03-01T14:20:00Z",
      "restricted_data_last_updated_at": null,
      "can_repackage": true,
      "needs_repackaging": false,
      "status": "ok",
      "user_role": "admin",
      "user_role_origin": "owner",
      "shared_datasets_project_id": null,
      "is_shared_datasets_project": false,
      "is_featured": false,
      "is_attachment_download_on_demand": false,
      "file_storage_bytes": 15728640
    }
  ]
}

Get Project

curl -X GET "https://app.qfield.cloud/api/v1/projects/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/v1/projects/{projectid}/ Retrieve details of a specific project.

Path Parameters

projectid

uuid

required

The unique identifier of the project

Response

Returns a single project object with the same structure as described in the List Projects response.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Tree Survey",
  "owner": "john_doe",
  "description": "Urban tree inventory project",
  "is_public": false,
  "private": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-03-01T14:20:00Z",
  "data_last_packaged_at": "2025-03-01T14:15:00Z",
  "data_last_updated_at": "2025-03-01T14:20:00Z",
  "restricted_data_last_updated_at": null,
  "can_repackage": true,
  "needs_repackaging": false,
  "status": "ok",
  "user_role": "admin",
  "user_role_origin": "owner",
  "shared_datasets_project_id": null,
  "is_shared_datasets_project": false,
  "is_featured": false,
  "is_attachment_download_on_demand": false,
  "file_storage_bytes": 15728640
}

Create Project

curl -X POST "https://app.qfield.cloud/api/v1/projects/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Survey 2026",
    "owner": "john_doe",
    "description": "Agricultural field survey",
    "is_public": false
  }'

POST /api/v1/projects/ Create a new project owned by the specified user or organization.

Request Body

name

string

required

Project name. Must be unique for the owner. Cannot be “shared_datasets” for regular projects.

owner

string

Username of the project owner. If not specified, defaults to the authenticated user.

description

string

Project description

is_public

boolean

Whether the project should be publicly accessible. Defaults to false.

Response

Returns the created project object.

{
  "id": "6f9e3c20-5a1b-42d5-b827-557766551111",
  "name": "Field Survey 2026",
  "owner": "john_doe",
  "description": "Agricultural field survey",
  "is_public": false,
  "private": true,
  "created_at": "2026-03-04T12:00:00Z",
  "updated_at": "2026-03-04T12:00:00Z",
  "data_last_packaged_at": null,
  "data_last_updated_at": null,
  "restricted_data_last_updated_at": null,
  "can_repackage": false,
  "needs_repackaging": false,
  "status": "ok",
  "user_role": "admin",
  "user_role_origin": "owner",
  "shared_datasets_project_id": null,
  "is_shared_datasets_project": false,
  "is_featured": false,
  "is_attachment_download_on_demand": false,
  "file_storage_bytes": 0
}

Error Responses

{
  "code": "project_already_exists",
  "message": "A project with this name already exists for this owner"
}

Update Project

curl -X PATCH "https://app.qfield.cloud/api/v1/projects/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "is_public": true
  }'

PATCH /api/v1/projects/{projectid}/ Partially update a project. You can also use PUT for a full update.

Path Parameters

projectid

uuid

required

The unique identifier of the project

Request Body

All fields are optional for PATCH requests.

name

string

Project name. Must be unique for the owner.

owner

string

Transfer project to a different owner. The new owner must have sufficient storage quota.

description

string

Project description

is_public

boolean

Whether the project should be publicly accessible

Response

Returns the updated project object.

Error Responses

{
  "code": "quota_error",
  "message": "Project storage too large for recipient's quota"
}

Delete Project

curl -X DELETE "https://app.qfield.cloud/api/v1/projects/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN"

DELETE /api/v1/projects/{projectid}/ Permanently delete a project and all its associated files and data.

Path Parameters

projectid

uuid

required

The unique identifier of the project to delete

Response

Returns HTTP 204 No Content on success.

Upload Project Thumbnail

curl -X POST "https://app.qfield.cloud/api/v1/projects/{projectid}/thumbnail/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "thumbnail=@/path/to/image.jpg"

POST /api/v1/projects/{projectid}/thumbnail/ Upload or update the project’s thumbnail image.

Path Parameters

projectid

uuid

required

The unique identifier of the project

Request Body

thumbnail

file

required

Image file for the project thumbnail

Response

Returns HTTP 204 No Content on success.

List Public Projects

curl -X GET "https://app.qfield.cloud/api/v1/projects/public/" \
  -H "Authorization: Token YOUR_TOKEN"

GET /api/v1/projects/public/ List all public projects.

Query Parameters

ordering

string

Order results by: owner, name, or created_at. Prefix with - for descending order.

limit

integer

Number of results to return per page

offset

integer

The initial index from which to return the results

Response

Returns a paginated list of public projects with the same structure as the List Projects endpoint.

Overview

Resources

Overview

List Projects

Query Parameters

Response

Get Project

Path Parameters

Response

Create Project

Request Body

Response

Error Responses

Update Project

Path Parameters

Request Body

Response

Error Responses

Delete Project

Path Parameters

Response

Upload Project Thumbnail

Path Parameters

Request Body

Response

List Public Projects

Query Parameters

Response

Build docs developers (and LLMs) love

Overview

Resources

​Overview

​List Projects

​Query Parameters

​Response

​Get Project

​Path Parameters

​Response

​Create Project

​Request Body

​Response

​Error Responses

​Update Project

​Path Parameters

​Request Body

​Response

​Error Responses

​Delete Project

​Path Parameters

​Response

​Upload Project Thumbnail

​Path Parameters

​Request Body

​Response

​List Public Projects

​Query Parameters

​Response

Build docs developers (and LLMs) love

Overview

List Projects

Query Parameters

Response

Get Project

Path Parameters

Response

Create Project

Request Body

Response

Error Responses

Update Project

Path Parameters

Request Body

Response

Error Responses

Delete Project

Path Parameters

Response

Upload Project Thumbnail

Path Parameters

Request Body

Response

List Public Projects

Query Parameters

Response