Skip to main content

​
Overview

Files are stored within projects and include QGIS project files, GeoPackage databases, images, and other geospatial data. QFieldCloud maintains version history for all files.

​
List Files

curl -X GET "https://app.qfield.cloud/api/v1/files/{project_id}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/files/{project_id}/ Get all file versions for a project.

​
Path Parameters

​
project_id
uuid
required
The unique identifier of the project

​
Query Parameters

​
skip_metadata
integer
Skip obtaining file metadata (e.g., sha256). Set to 1 for faster responses. Default: 0

​
Response

Returns an array of file objects.
​
name
string
File name including path relative to project root
​
size
integer
File size in bytes (latest version)
​
md5sum
string
MD5 checksum of the file
​
sha256
string
SHA256 checksum of the file (only when skip_metadata=0)
​
last_modified
datetime
When the file was last modified
​
is_attachment
boolean
Whether the file is an attachment
​
versions
array
Array of all file versions
​
version_id
string
Unique identifier for this version
​
size
integer
File size in bytes for this version
​
md5sum
string
MD5 checksum for this version
​
sha256
string
SHA256 checksum for this version (only when skip_metadata=0)
​
last_modified
datetime
When this version was created
​
is_latest
boolean
Whether this is the latest version
​
display
string
Display name for this version
[
  {
    "name": "project.qgs",
    "size": 45678,
    "md5sum": "5d41402abc4b2a76b9719d911017c592",
    "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
    "last_modified": "2026-03-04T10:30:00Z",
    "is_attachment": false,
    "versions": [
      {
        "version_id": "v1.550e8400.e29b",
        "size": 45678,
        "md5sum": "5d41402abc4b2a76b9719d911017c592",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "last_modified": "2026-03-04T10:30:00Z",
        "is_latest": true,
        "display": "Current"
      },
      {
        "version_id": "v1.550e8400.e29a",
        "size": 45120,
        "md5sum": "098f6bcd4621d373cade4e832627b4f6",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "last_modified": "2026-03-03T14:20:00Z",
        "is_latest": false,
        "display": "Version from 2026-03-03"
      }
    ]
  },
  {
    "name": "data/survey.gpkg",
    "size": 2048576,
    "md5sum": "e99a18c428cb38d5f260853678922e03",
    "sha256": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b2b7d0e8c2c3e9f3c5f6e5d4c",
    "last_modified": "2026-03-04T11:15:00Z",
    "is_attachment": false,
    "versions": [
      {
        "version_id": "v1.6f9e3c20.5a1b",
        "size": 2048576,
        "md5sum": "e99a18c428cb38d5f260853678922e03",
        "sha256": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b2b7d0e8c2c3e9f3c5f6e5d4c",
        "last_modified": "2026-03-04T11:15:00Z",
        "is_latest": true,
        "display": "Current"
      }
    ]
  }
]

​
Get File

curl -X GET "https://app.qfield.cloud/api/v1/files/{project_id}/{filename}" \
  -H "Authorization: Token YOUR_TOKEN" \
  --output downloaded_file
GET /api/v1/files/{project_id}/{filename} Download a specific file from a project.

​
Path Parameters

​
project_id
uuid
required
The unique identifier of the project
​
filename
string
required
The file path relative to the project root (e.g., data/survey.gpkg)

​
Query Parameters

​
version_id
string
Download a specific version of the file. If not provided, downloads the latest version.

​
Response

Returns the file content as a binary stream with appropriate Content-Type headers.

​
Upload File

curl -X POST "https://app.qfield.cloud/api/v1/files/{project_id}/{filename}" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "file=@/path/to/local/file.gpkg"
POST /api/v1/files/{project_id}/{filename} Upload a file to a project. Creates a new version if the file already exists.

​
Path Parameters

​
project_id
uuid
required
The unique identifier of the project
​
filename
string
required
The destination file path relative to the project root

​
Request Body

​
file
file
required
The file to upload (multipart/form-data)

​
Response

Returns HTTP 201 Created on success. 
{
  "name": "data/survey.gpkg",
  "version_id": "v1.7a8b9c10.2d3e",
  "size": 2048576,
  "uploaded_at": "2026-03-04T12:00:00Z"
}

​
Error Responses

{
  "code": "quota_error",
  "message": "Storage quota exceeded. Please upgrade your plan or free up space."
}

{
  "code": "invalid_file",
  "message": "This file type is not allowed or the file is corrupted."
}

​
Delete File

curl -X DELETE "https://app.qfield.cloud/api/v1/files/{project_id}/{filename}" \
  -H "Authorization: Token YOUR_TOKEN"
DELETE /api/v1/files/{project_id}/{filename} Delete a specific file version from a project.

​
Path Parameters

​
project_id
uuid
required
The unique identifier of the project
​
filename
string
required
The file path relative to the project root

​
Query Parameters

​
version_id
string
Delete a specific version. If not provided, deletes the latest version.

​
Response

Returns HTTP 204 No Content on success.

​
Get File Metadata

curl -X GET "https://app.qfield.cloud/api/v1/files/metadata/{project_id}/{filename}" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/files/metadata/{project_id}/{filename} Get metadata for a specific file without downloading it.

​
Path Parameters

​
project_id
uuid
required
The unique identifier of the project
​
filename
string
required
The file path relative to the project root

​
Response

​
name
string
File name
​
size
integer
File size in bytes
​
md5sum
string
MD5 checksum
​
sha256
string
SHA256 checksum
​
last_modified
datetime
When the file was last modified
​
content_type
string
MIME type of the file
{
  "name": "data/survey.gpkg",
  "size": 2048576,
  "md5sum": "e99a18c428cb38d5f260853678922e03",
  "sha256": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b2b7d0e8c2c3e9f3c5f6e5d4c",
  "last_modified": "2026-03-04T11:15:00Z",
  "content_type": "application/geopackage+sqlite3"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us