API Overview - QFieldCloud

Introduction

QFieldCloud provides a comprehensive REST API built with Django REST Framework. The API allows you to programmatically manage projects, files, collaborators, teams, and field data synchronization. All API requests should be made to:

https://your-instance.qfieldcloud.com/api/v1/

API Version

The current API version is v1, indicated by the /api/v1/ prefix in all endpoints.

Base URL

The base URL for all API requests follows this pattern:

https://{QFIELDCLOUD_HOST}/api/v1/

Replace {QFIELDCLOUD_HOST} with your QFieldCloud instance domain.

Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

Success Response

Successful requests return data with HTTP 200, 201, or 204 status codes:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Project",
  "owner": "username",
  "created_at": "2024-03-04T10:30:00Z"
}

Error Response

Error responses include a descriptive error code and message:

{
  "code": "validation_error",
  "message": "Validation error",
  "detail": "Project name is required"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource successfully created
`204`	No Content - Request succeeded with no response body
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Authentication failed or token invalid
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`416`	Range Not Satisfiable - Invalid HTTP Range header
`500`	Internal Server Error - Server error

Error Codes

QFieldCloud uses specific error codes to help identify issues:

Error Code	HTTP Status	Description
`authentication_failed`	401	Authentication credentials are incorrect
`token_authentication_failed`	401	Invalid or expired authentication token
`not_authenticated`	401	Authentication required but not provided
`too_many_failed_login_attempts`	401	Account locked due to too many failed login attempts
`permission_denied`	403	User lacks required permissions for this action
`object_not_found`	404	Requested resource does not exist
`validation_error`	400	Request data validation failed
`empty_content`	400	Required content (e.g., file) is missing
`multiple_contents`	400	Multiple files provided when only one expected
`multiple_projects`	400	Attempting to upload multiple QGIS projects
`project_already_exists`	400	Project with this name already exists
`no_qgis_project`	400	Project does not contain a valid QGIS project file
`invalid_deltafile`	400	Deltafile validation failed
`no_deltas_to_apply`	400	No deltas available to apply
`invalid_job`	400	Invalid job identifier
`invalid_http_range`	416	HTTP Range header is malformed
`qgis_project_file_not_allowed`	400	QGIS project files not permitted in this project type
`restricted_project_modification`	403	Insufficient role to modify restricted project files
`api_error`	500	Internal API error

Pagination

List endpoints use limit-offset pagination with pagination metadata returned in response headers.

Query Parameters

limit

integer

default:"50"

Maximum number of results to return per page. Default is 50.

offset

integer

default:"0"

Number of results to skip before returning data. Use for pagination.

Response Headers

The API returns pagination metadata in custom headers:

Header	Description
`X-Total-Count`	Total number of available results
`X-Next-Page`	URL to the next page of results (if available)
`X-Previous-Page`	URL to the previous page of results (if available)

Example Request

curl -H "Authorization: Token YOUR_TOKEN" \
  "https://app.qfieldcloud.com/api/v1/projects/?limit=20&offset=40"

Example Response Headers

X-Total-Count: 156
X-Next-Page: https://app.qfieldcloud.com/api/v1/projects/?limit=20&offset=60
X-Previous-Page: https://app.qfieldcloud.com/api/v1/projects/?limit=20&offset=20

Rate Limits

QFieldCloud does not currently enforce strict rate limits, but we recommend:

Implementing exponential backoff for retries
Avoiding excessive concurrent requests
Caching responses when appropriate
Using webhooks for event notifications instead of polling

Rate limiting may be introduced in future versions. Monitor API response headers for any rate limit information.

OpenAPI Schema

QFieldCloud provides a complete OpenAPI schema for the API:

Swagger UI: https://{QFIELDCLOUD_HOST}/swagger/
ReDoc: https://{QFIELDCLOUD_HOST}/docs/
OpenAPI YAML: https://{QFIELDCLOUD_HOST}/swagger.yaml

The schema is generated using drf-spectacular and provides interactive documentation.

Client Libraries

Official SDK

QFieldCloud provides an official Python SDK:

pip install qfieldcloud-sdk

The SDK handles authentication, pagination, and provides type hints for all API operations.

User-Agent Header

When making API requests, include a descriptive User-Agent header to identify your client:

User-Agent: sdk|your-app-name/1.0.0
User-Agent: cli|your-cli-tool/2.1.0
User-Agent: qfield|QField/3.0.0

The API uses the User-Agent to:

Track client types for analytics
Apply appropriate token expiration policies
Provide client-specific functionality

Common Patterns

Creating Resources

Use POST requests with JSON body:

curl -X POST https://app.qfieldcloud.com/api/v1/projects/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Survey 2024",
    "description": "Annual field survey project"
  }'

Updating Resources

Use PATCH for partial updates or PUT for full replacement:

curl -X PATCH https://app.qfieldcloud.com/api/v1/projects/{project_id}/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description"
  }'

Deleting Resources

Use DELETE requests:

curl -X DELETE https://app.qfieldcloud.com/api/v1/projects/{project_id}/ \
  -H "Authorization: Token YOUR_TOKEN"

File Uploads

File upload endpoints accept multipart form data:

curl -X POST https://app.qfieldcloud.com/api/v1/files/{project_id}/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "file=@/path/to/file.gpkg"

Next Steps

Authentication

Learn how to authenticate API requests

Projects API

Manage QFieldCloud projects

Files API

Upload and manage project files

OpenAPI Docs

Interactive API documentation

Overview

Resources

​Introduction

​API Version

​Base URL

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Error Codes

​Pagination

​Query Parameters

​Response Headers

​Example Request

​Example Response Headers

​Rate Limits

​OpenAPI Schema

​Client Libraries

​Official SDK

​User-Agent Header

​Common Patterns

​Creating Resources

​Updating Resources

​Deleting Resources

​File Uploads

​Next Steps