Projects

​

Overview

​

Project Model

​

Key Fields

• id: UUID primary key, auto-generated
• name: Project name (alphanumeric, underscores, hyphens, dots allowed)
• description: Optional text description
• owner: Foreign key to User (Person or Organization)
• is_public: Boolean flag for project visibility
• the_qgis_file_name: Name of the main QGIS project file (.qgs/.qgz)
• project_details: JSON field containing parsed project metadata
• created_at: Timestamp of project creation
• updated_at: Timestamp of last update
• file_storage: Storage backend name (e.g., “s3”, “minio”)
• file_storage_bytes: Cached size of project files

​

Creating a Project

​

API Endpoint

POST /api/v1/projects/

​

Request Body

{
  "name": "field_survey_2024",
  "description": "Field data collection for Q1 2024",
  "owner": "username",
  "is_public": false
}

​

Example with cURL

curl -X POST https://app.qfield.cloud/api/v1/projects/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_project",
    "owner": "username",
    "is_public": false
  }'

​

Permissions

• Have an active account
• Have sufficient storage quota
• Be the owner or have admin rights to the organization (if creating for an organization)

​

Project Visibility

​

Public Projects

• Visible to all authenticated users
• Read-only access for non-collaborators
• Owner and collaborators retain edit permissions
• Listed in the public projects endpoint

GET /api/v1/public-projects/

​

Private Projects

• Only visible to owner and collaborators
• Access controlled by collaboration roles
• Subject to subscription limits on collaborators

​

Project Settings

​

File Storage Configuration

file_storage = models.CharField(
    max_length=100,
    default=get_project_file_storage_default,
    validators=[validators.file_storage_name_validator],
)

​

Attachment Storage

attachments_file_storage = models.CharField(
    max_length=100,
    default=get_project_attachments_file_storage_default,
)

​

Version Control

storage_keep_versions = models.PositiveIntegerField(
    null=True,
    blank=True,
    validators=[MinValueValidator(1), MaxValueValidator(100)],
)

​

Conflict Resolution

overwrite_conflicts = models.BooleanField(
    default=True,
    help_text="Automatically overwrite conflicts or require manual resolution"
)

​

Restricted Project Files

has_restricted_projectfiles = models.BooleanField(
    default=False,
    help_text="Restrict QGIS project file modifications to managers and administrators"
)

​

Project Lifecycle

​

1. Creation

• UUID is auto-generated
• Owner’s storage quota is checked
• Storage backend is initialized
• Timestamps are set

​

2. File Upload

POST /api/v1/files/{projectid}/{filename}/

• A ProcessProjectfileJob is automatically triggered
• Project metadata is extracted into project_details
• Layer information is parsed and validated

​

3. Active Use

• Files can be uploaded/downloaded
• Deltas are created from mobile edits
• Packaging jobs prepare data for offline use
• Collaborators can be added/removed

​

4. Deletion

DELETE /api/v1/projects/{projectid}/

• Removes all associated files from storage
• Deletes all collaborators
• Removes all jobs and deltas
• Cannot be undone

​

Project Status

​

Status Values

• ok: Project is ready to use
• busy: Background jobs are running
• failed: Project has configuration errors

​

Status Codes

• ok: No issues
• failed_process_projectfile: Missing or invalid QGIS project file
• too_many_collaborators: Exceeds subscription limit

​

Querying Projects

​

List User’s Projects

GET /api/v1/projects/

• The owner
• A collaborator
• Organization member (for organization-owned projects)

​

Filtering

projects = Project.objects.for_user(user, skip_invalid=False)

• user_role: The user’s role on the project
• user_role_origin: How the role was assigned (owner, collaborator, organization, etc.)
• user_role_is_valid: Whether the role is currently valid

​

Special Project Types

​

Shared Datasets Project

SHARED_DATASETS_PROJECT_NAME = "shared_datasets"

• Stores shared data layers
• Cannot contain QGIS project files
• Provides data to other projects via localized layers

​

API Reference

​

Retrieve Project

GET /api/v1/projects/{projectid}/

​

Update Project

PATCH /api/v1/projects/{projectid}/

{
  "description": "Updated description",
  "is_public": true
}

​

Transfer Ownership

PATCH /api/v1/projects/{projectid}/

{
  "owner": "new_owner_username"
}

​

Related Resources

• Collaboration - Managing project collaborators
• File Management - Uploading and managing project files
• Synchronization - Syncing with QField mobile