Skip to main content

​
Overview

Deltas represent incremental changes made to project data in QField. They are used for synchronization and conflict resolution between field devices and the cloud.

​
List Deltas

curl -X GET "https://app.qfield.cloud/api/v1/deltas/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/deltas/{projectid}/ Get all deltas 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 deltas
​
next
string
URL to the next page of results
​
previous
string
URL to the previous page of results
​
results
array
Array of delta objects
​
id
uuid
Unique delta identifier
​
deltafile_id
uuid
ID of the deltafile containing this delta
​
created_by
string
Username of the user who created the delta
​
created_at
datetime
When the delta was created
​
updated_at
datetime
When the delta was last updated
​
status
string
Delta status: STATUS_PENDING, STATUS_BUSY, STATUS_APPLIED, STATUS_CONFLICT, STATUS_NOT_APPLIED, STATUS_ERROR, STATUS_IGNORED, or STATUS_UNPERMITTED
​
output
string
Feedback message about the delta processing
​
last_status
string
Internal status code
​
last_feedback
object
Detailed feedback object
​
content
object
Delta content with the actual changes
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "7f8e9d10-2c3b-4a5d-e6f7-889900112233",
      "deltafile_id": "8g9f0e21-3d4c-5b6e-f7g8-990011223344",
      "created_by": "field_user",
      "created_at": "2026-03-04T09:30:00Z",
      "updated_at": "2026-03-04T09:31:00Z",
      "status": "STATUS_APPLIED",
      "output": "Delta applied successfully",
      "last_status": "applied",
      "last_feedback": {
        "msg": "Delta applied successfully"
      },
      "content": {
        "uuid": "7f8e9d10-2c3b-4a5d-e6f7-889900112233",
        "clientId": "device-123",
        "localLayerId": "trees_layer",
        "method": "create",
        "new": {
          "geometry": "POINT(7.5 47.5)",
          "attributes": {
            "species": "Oak",
            "height": 15.5
          }
        }
      }
    },
    {
      "id": "8g9f0e21-3d4c-5b6e-f7g8-990011223345",
      "deltafile_id": "8g9f0e21-3d4c-5b6e-f7g8-990011223344",
      "created_by": "field_user",
      "created_at": "2026-03-04T09:30:01Z",
      "updated_at": "2026-03-04T09:31:01Z",
      "status": "STATUS_CONFLICT",
      "output": "Conflict detected: feature was modified by another user",
      "last_status": "conflict",
      "last_feedback": {
        "msg": "Conflict detected: feature was modified by another user",
        "conflict_type": "edit_edit"
      },
      "content": {
        "uuid": "8g9f0e21-3d4c-5b6e-f7g8-990011223345",
        "clientId": "device-123",
        "localLayerId": "trees_layer",
        "method": "patch",
        "old": {
          "fid": 42,
          "attributes": {
            "height": 15.0
          }
        },
        "new": {
          "attributes": {
            "height": 15.8
          }
        }
      }
    }
  ]
}

​
Upload Deltafile

curl -X POST "https://app.qfield.cloud/api/v1/deltas/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "[email protected]"
POST /api/v1/deltas/{projectid}/ Upload a deltafile to the project. The deltafile contains multiple deltas representing changes made in QField.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project

​
Request Body

​
file
file
required
JSON deltafile containing an array of deltas (multipart/form-data)

​
Deltafile Format

The deltafile must be a JSON file with the following structure: 
{
  "id": "8g9f0e21-3d4c-5b6e-f7g8-990011223344",
  "project": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1.0",
  "deltas": [
    {
      "uuid": "7f8e9d10-2c3b-4a5d-e6f7-889900112233",
      "clientId": "device-123",
      "localLayerId": "trees_layer",
      "method": "create",
      "sourcePk": null,
      "new": {
        "geometry": "POINT(7.5 47.5)",
        "attributes": {
          "species": "Oak",
          "height": 15.5
        }
      }
    }
  ]
}

​
Response

Returns HTTP 200 OK on success. The deltas are created and an apply job is automatically triggered.

​
Error Responses

{
  "code": "no_qgis_project",
  "message": "Project must contain a QGIS project file (.qgs or .qgz)"
}

{
  "code": "deltafile_validation_error",
  "message": "Deltafile's project id (abc...) doesn't match URL parameter project id (xyz...)"
}

{
  "code": "empty_content",
  "message": "The uploaded file is empty or missing"
}

​
List Deltas by Deltafile

curl -X GET "https://app.qfield.cloud/api/v1/deltas/{projectid}/{deltafileid}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/deltas/{projectid}/{deltafileid}/ List all deltas belonging to a specific deltafile.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project
​
deltafileid
uuid
required
The unique identifier of the deltafile

​
Query Parameters

​
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 delta objects with the same structure as the List Deltas endpoint.

​
Apply Deltas (Deprecated)

curl -X POST "https://app.qfield.cloud/api/v1/deltas/apply/{projectid}/" \
  -H "Authorization: Token YOUR_TOKEN"
POST /api/v1/deltas/apply/{projectid}/
This endpoint is deprecated and will be removed in the future. Please use the /api/v1/jobs/ endpoint with type delta_apply instead.
Manually trigger delta application for a project.

​
Path Parameters

​
projectid
uuid
required
The unique identifier of the project

​
Response

Returns HTTP 200 OK when the apply job is triggered.

​
Delta Statuses

Deltas can have the following statuses:
  • STATUS_PENDING: Delta is waiting to be processed
  • STATUS_BUSY: Delta is currently being applied
  • STATUS_APPLIED: Delta was successfully applied
  • STATUS_CONFLICT: Delta conflicts with existing data
  • STATUS_NOT_APPLIED: Delta was not applied (e.g., validation failed)
  • STATUS_ERROR: An error occurred during processing
  • STATUS_IGNORED: Delta was intentionally ignored
  • STATUS_UNPERMITTED: User doesn’t have permission to apply this delta

​
Delta Methods

Deltas support the following methods:
  • create: Create a new feature
  • patch: Update an existing feature’s attributes
  • delete: Delete a feature

Build docs developers (and LLMs) love

Get started for freeTalk to us