Tasks API — Lock, Map, and Validate Mapping Tasks

Tasks are the individual mapping units within a Tasking Manager project. Each task corresponds to a geographic tile or custom polygon that a mapper can lock, edit in an external editor (iD, JOSM, RAPID, etc.), and submit back with a status. Validators then review mapped tasks, marking them VALIDATED or sending them back as INVALIDATED. This page documents all task resource and action endpoints. All authenticated endpoints require an Authorization: Token <session_token> header. The API base path is /api/v2.

Task Resources

List All Tasks for a Project

GET /api/v2/projects/{project_id}/tasks/ Returns all tasks for a project as a GeoJSON FeatureCollection. Private or draft projects enforce authentication. Optionally filter to a specific subset of task IDs, or download the result as a file.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Query Parameters

tasks

string

Comma-separated list of task IDs to retrieve (e.g., 1,2,5). Omit to retrieve all tasks.

as_file

boolean

default:"false"

When true, returns the response as a downloadable application/geo+json file.

Responses

Status	Description
`200`	GeoJSON FeatureCollection of tasks.
`403`	User not permitted to access private or draft project.
`404`	Project not found.
`500`	Internal server error.

Get a Single Task

GET /api/v2/projects/{project_id}/tasks/{task_id}/ Returns metadata for a single task, including its current status, lock holder, task history, and geometry. No authentication required for public projects.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/7/" \
  -H "Accept-Language: en"

Path Parameters

project_id

integer

required

Project ID the task belongs to.

task_id

integer

required

Unique task ID within the project.

Response Fields

taskId

integer

The task’s numeric ID within the project.

taskStatus

string

Current task status. One of: READY, LOCKED_FOR_MAPPING, MAPPED, LOCKED_FOR_VALIDATION, VALIDATED, INVALIDATED, BADIMAGERY, SPLIT.

lockHolder

string

OSM username of the user who currently holds the lock, or null if unlocked.

taskHistory

array

Ordered list of status-change history events for this task.

geometry

object

GeoJSON geometry for the task boundary.

Responses

Status	Description
`200`	Task metadata returned.
`404`	Task or project not found.
`500`	Internal server error.

Get Mapped Tasks by User

GET /api/v2/projects/{project_id}/tasks/queries/mapped/ Returns all mapped tasks for a project grouped by the username of the mapper.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/queries/mapped/"

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Mapped tasks returned, grouped by mapper username.
`500`	Internal server error.

Get Tasks as OSM XML

GET /api/v2/projects/{project_id}/tasks/queries/xml/ Returns tasks for a project in OSM XML format, suitable for import into JOSM or other OSM editors.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/queries/xml/?tasks=1,2" \
  -o project-1234.osm

Path Parameters

project_id

integer

required

Unique project ID.

Query Parameters

tasks

string

Comma-separated task IDs. Omit to retrieve all tasks.

as_file

boolean

default:"false"

When true, returns the response as a downloadable .osm file.

Responses

Status	Description
`200`	OSM XML returned.
`400`	Client error.
`404`	No mapped tasks found.
`500`	Internal server error.

Get Tasks as GPX

GET /api/v2/projects/{project_id}/tasks/queries/gpx/ Returns tasks for a project in GPX format.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/queries/gpx/?tasks=1,2" \
  -o project-1234.gpx

Path Parameters

project_id

integer

required

Unique project ID.

Query Parameters

tasks

string

Comma-separated task IDs. Omit to retrieve all tasks.

as_file

boolean

default:"false"

When true, returns the response as a downloadable .gpx file.

Responses

Status	Description
`200`	GPX XML returned.
`400`	Client error.
`404`	No mapped tasks found.
`500`	Internal server error.

Task Actions

The task action endpoints form the core of the mapping and validation workflow. The typical lifecycle is:

Lock the task (lock-for-mapping)
Edit features in your chosen editor using the task’s bounding box
Unlock with a result status (unlock-after-mapping)

Validation follows a similar pattern with lock-for-validation and unlock-after-validation.

Lock Task for Mapping

POST /api/v2/projects/{project_id}/tasks/actions/lock-for-mapping/{task_id}/ Locks a READY or INVALIDATED task for the authenticated user to map. Only one task per project may be locked by a user at a time. Returns the updated task object.

If the project requires a license agreement and the user has not accepted it, this endpoint returns 409 Conflict with SubCode: UserLicenseError.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/lock-for-mapping/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"

Path Parameters

project_id

integer

required

Project ID the task belongs to.

task_id

integer

required

ID of the task to lock.

Responses

Status	Description
`200`	Task locked. Returns updated task DTO.
`400`	Invalid request.
`401`	Missing or invalid token.
`403`	Task cannot be locked (e.g., already locked, wrong status, insufficient mapping level).
`404`	Task or project not found.
`409`	User has not accepted the project’s license terms.
`500`	Internal server error.

Unlock After Mapping (Submit Result)

POST /api/v2/projects/{project_id}/tasks/actions/unlock-after-mapping/{task_id}/ Unlocks a task after the user has finished editing, submitting a new status. The mapper must currently hold the lock on the task.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/unlock-after-mapping/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "MAPPED",
    "comment": "Mapped all buildings visible in imagery"
  }'

Path Parameters

project_id

integer

required

Project ID the task belongs to.

task_id

integer

required

ID of the task to unlock.

Request Body

status

string

required

The result status for the task. Valid values: MAPPED (edit complete), BADIMAGERY (imagery quality prevents mapping), READY (return to ready without mapping).

comment

string

Optional text comment for the task history log.

Responses

Status	Description
`200`	Task unlocked. Returns updated task DTO.
`400`	Invalid request body or status value.
`401`	Missing or invalid token.
`403`	User does not hold the lock on this task.
`404`	Task or project not found.
`500`	Internal server error.

Stop Mapping (Release Lock Without Submitting)

POST /api/v2/projects/{project_id}/tasks/actions/stop-mapping/{task_id}/ Releases the mapping lock without changing the task status. Use this when a mapper needs to abandon a task mid-session. The task reverts to its previous status.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/stop-mapping/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Stopping for now, will continue later"}'

Path Parameters

project_id

integer

required

Project ID.

task_id

integer

required

ID of the locked task.

Request Body

comment

string

Optional comment added to the task history.

Responses

Status	Description
`200`	Lock released. Returns updated task DTO.
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	User does not hold the lock on this task.
`404`	Task or project not found.

Undo Last Action

POST /api/v2/projects/{project_id}/tasks/actions/undo-last-action/{task_id}/ Reverts a task to its previous status, undoing the last mapping or validation action. Requires authentication.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/undo-last-action/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"

Path Parameters

project_id

integer

required

Project ID.

task_id

integer

required

ID of the task to revert.

Responses

Status	Description
`200`	Task reverted. Returns updated task DTO.
`403`	User is not permitted to undo this action.
`404`	Task or project not found.
`500`	Internal server error.

Lock Tasks for Validation

POST /api/v2/projects/{project_id}/tasks/actions/lock-for-validation/ Locks one or more MAPPED tasks for validation by the authenticated user. Accepts an array of task IDs. Returns the list of locked tasks.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/lock-for-validation/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{"taskIds": [7, 8, 9]}'

Path Parameters

project_id

integer

required

Project ID.

Request Body

taskIds

array

required

Array of integer task IDs to lock for validation. All tasks must be in MAPPED status.

Responses

Status	Description
`200`	Tasks locked. Returns list of locked task objects.
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	Tasks cannot be locked (wrong status, insufficient validator level, etc.).
`404`	Project not found.
`409`	User has not accepted the project’s license terms.
`500`	Internal server error.

Unlock After Validation (Submit Validation Result)

POST /api/v2/projects/{project_id}/tasks/actions/unlock-after-validation/ Submits validation results for one or more tasks currently locked for validation by the authenticated user.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/unlock-after-validation/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "validatedTasks": [
      {
        "taskId": 7,
        "status": "VALIDATED",
        "comment": "All buildings correctly mapped"
      },
      {
        "taskId": 8,
        "status": "INVALIDATED",
        "comment": "Several buildings missed in the north-east corner"
      }
    ]
  }'

Path Parameters

project_id

integer

required

Project ID.

Request Body

validatedTasks

array

required

Array of validation result objects.

Show validatedTasks item

taskId

integer

required

ID of the task being validated.

status

string

required

Validation outcome. Valid values: VALIDATED (mapping accepted), INVALIDATED (mapping needs revision).

comment

string

Optional feedback comment for the original mapper.

Responses

Status	Description
`200`	Validation submitted. Returns list of updated task objects.
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	User does not hold the validation lock on one or more tasks.
`404`	Project not found.
`500`	Internal server error.

Stop Validation (Release Validation Lock)

POST /api/v2/projects/{project_id}/tasks/actions/stop-validation/ Releases validation locks without submitting results, reverting locked tasks to their previous status. Used when a validator needs to abandon a session.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/stop-validation/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "resetTasks": [
      {"taskId": 7, "comment": "Will return to validate later"},
      {"taskId": 8}
    ]
  }'

Path Parameters

project_id

integer

required

Project ID.

Request Body

resetTasks

array

required

Array of task objects to release.

Show resetTasks item

taskId

integer

required

ID of the task to release.

comment

string

Optional comment added to the task history.

Responses

Status	Description
`200`	Locks released. Returns updated task list.
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	User does not hold the lock on one or more tasks.
`404`	Project not found.

Extend Task Lock Time

POST /api/v2/projects/{project_id}/tasks/actions/extend/ Extends the lock expiry time for one or more tasks currently locked by the authenticated user. Useful for long mapping sessions.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/extend/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{"taskIds": [7, 8]}'

Path Parameters

project_id

integer

required

Project ID.

Request Body

taskIds

array

required

Array of integer task IDs whose lock time should be extended.

Responses

Status	Description
`200`	Lock time extended. Body: `{"Success": "Successfully extended task expiry"}`
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	User does not hold the lock on one or more tasks.
`404`	Project not found.
`500`	Internal server error.

Map All Tasks

POST /api/v2/projects/{project_id}/tasks/actions/map-all/ Marks all tasks in the project as MAPPED. Requires project manager or admin role.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/map-all/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Body: `{"Success": "All tasks mapped"}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Validate All Tasks

POST /api/v2/projects/{project_id}/tasks/actions/validate-all/ Marks all mapped tasks in the project as VALIDATED. Requires project manager or admin role.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/validate-all/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Body: `{"Success": "All tasks validated"}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Invalidate All Tasks

POST /api/v2/projects/{project_id}/tasks/actions/invalidate-all/ Marks all validated tasks in the project as INVALIDATED. Requires project manager or admin role.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/invalidate-all/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Body: `{"Success": "All tasks invalidated"}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Reset Bad Imagery Tasks

POST /api/v2/projects/{project_id}/tasks/actions/reset-all-badimagery/ Resets all tasks in BADIMAGERY status back to READY, allowing them to be picked up for mapping again. Requires project manager or admin role.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/reset-all-badimagery/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Body: `{"Success": "All bad imagery tasks marked ready for mapping"}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Reset All Tasks

POST /api/v2/projects/{project_id}/tasks/actions/reset-all/ Resets every task in the project back to READY status, preserving the task history. Requires project manager or admin role.

This will undo all mapping and validation progress for the project. Task history entries are preserved but all task statuses return to READY.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/reset-all/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Body: `{"Success": "All tasks reset"}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Revert Tasks by User

POST /api/v2/projects/{project_id}/tasks/actions/reset-by-user/ Reverts tasks previously actioned by a specific user within the project. For example, reverts all tasks a user marked as BADIMAGERY or VALIDATED. Requires project manager or admin role.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/reset-by-user/?username=badmapper&action=VALIDATED" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

project_id

integer

required

Project ID.

Query Parameters

username

string

required

Username of the user whose task actions should be reverted.

action

string

required

The action type to revert. Valid values: BADIMAGERY, VALIDATED.

Responses

Status	Description
`200`	Body: `{"Success": "Successfully reverted tasks"}`
`400`	Username or action not provided, or invalid data.
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Split a Task

POST /api/v2/projects/{project_id}/tasks/actions/split/{task_id}/ Splits a single task into four smaller subtasks. Only tasks in READY status that cover a minimum area and have not reached the maximum zoom level can be split. Returns the newly created subtask objects.

Task splitting is useful when a task covers a densely built-up area that is too large to map accurately in one session. Each of the four resulting tasks can be independently locked and mapped.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/split/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"

Path Parameters

project_id

integer

required

Project ID.

task_id

integer

required

ID of the task to split. The task must be in READY status and large enough to subdivide.

Responses

Status	Description
`200`	Task split. Returns the four new subtask objects.
`400`	Invalid request.
`401`	Missing or invalid token.
`403`	Task cannot be split (too small, wrong status, or insufficient permissions).
`404`	Task or project not found.
`500`	Internal server error.

Task Statistics

Get Task Statistics

GET /api/v2/tasks/statistics/ Returns aggregated task completion statistics across the platform, filterable by date range, organisation, campaign, project, and country. Requires authentication. Date range cannot exceed 366 days.

This is a global statistics endpoint under /api/v2/tasks/, not under a specific project. Use the project statistics endpoint (/api/v2/projects/{project_id}/statistics/) for per-project counts.

curl "https://tasking-manager-api.hotosm.org/api/v2/tasks/statistics/?startDate=2024-01-01&endDate=2024-06-30" \
  -H "Authorization: Token sessionTokenHere=="

Query Parameters

startDate

string

required

Start date in YYYY-MM-DD format. Defines the lower bound of the date range.

endDate

string

default:"today"

End date in YYYY-MM-DD format. Defaults to today. Cannot be earlier than startDate. Date range cannot exceed 366 days.

organisationId

string

Filter by organisation ID.

organisationName

string

Filter by organisation name.

campaign

string

Filter by campaign name.

projectId

string

Comma-separated project IDs to filter results.

country

string

Filter by country name.

Responses

Status	Description
`200`	Task statistics returned.
`400`	Invalid date format or range exceeds 366 days.
`401`	Missing or invalid token.
`500`	Internal server error.

Full Mapping Workflow Example

The following example shows a complete lock → edit → submit workflow for a single task.

curl -X POST \
  "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/tasks/actions/lock-for-mapping/7/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"
# Response includes task geometry and editor URLs for iD, JOSM, etc.

Overview

Resources

Documentation Index

​Task Resources

​List All Tasks for a Project

​Path Parameters

​Query Parameters

​Responses

​Get a Single Task

​Path Parameters

​Response Fields

​Responses

​Get Mapped Tasks by User

​Path Parameters

​Responses

​Get Tasks as OSM XML

​Path Parameters

​Query Parameters

​Responses

​Get Tasks as GPX

​Path Parameters

​Query Parameters

​Responses

​Task Actions

​Lock Task for Mapping

​Path Parameters

​Responses

​Unlock After Mapping (Submit Result)

​Path Parameters

​Request Body

​Responses

​Stop Mapping (Release Lock Without Submitting)

​Path Parameters

​Request Body

​Responses

​Undo Last Action

​Path Parameters

​Responses

​Lock Tasks for Validation

​Path Parameters

​Request Body

​Responses

​Unlock After Validation (Submit Validation Result)

​Path Parameters

​Request Body

​Responses

​Stop Validation (Release Validation Lock)

​Path Parameters

​Request Body

​Responses

​Extend Task Lock Time

​Path Parameters

​Request Body

​Responses

​Map All Tasks

​Path Parameters

​Responses

​Validate All Tasks

​Path Parameters

​Responses

​Invalidate All Tasks

​Path Parameters

​Responses

​Reset Bad Imagery Tasks

​Path Parameters

​Responses

​Reset All Tasks

​Path Parameters

​Responses

​Revert Tasks by User

​Path Parameters

​Query Parameters

​Responses

​Split a Task

​Path Parameters

​Responses

​Task Statistics

​Get Task Statistics

​Query Parameters

​Responses

Task Resources

List All Tasks for a Project

Path Parameters

Query Parameters

Responses

Get a Single Task

Path Parameters

Response Fields

Responses

Get Mapped Tasks by User

Path Parameters

Responses

Get Tasks as OSM XML

Path Parameters

Query Parameters

Responses

Get Tasks as GPX

Path Parameters

Query Parameters

Responses

Task Actions

Lock Task for Mapping

Path Parameters

Responses

Unlock After Mapping (Submit Result)

Path Parameters

Request Body

Responses

Stop Mapping (Release Lock Without Submitting)

Path Parameters

Request Body

Responses

Undo Last Action

Path Parameters

Responses

Lock Tasks for Validation

Path Parameters

Request Body

Responses

Unlock After Validation (Submit Validation Result)

Path Parameters

Request Body

Responses

Stop Validation (Release Validation Lock)

Path Parameters

Request Body

Responses

Extend Task Lock Time

Path Parameters

Request Body

Responses

Map All Tasks

Path Parameters

Responses

Validate All Tasks

Path Parameters

Responses

Invalidate All Tasks

Path Parameters

Responses

Reset Bad Imagery Tasks

Path Parameters

Responses

Reset All Tasks

Path Parameters

Responses

Revert Tasks by User

Path Parameters

Query Parameters

Responses

Split a Task

Path Parameters

Responses

Task Statistics

Get Task Statistics

Query Parameters

Responses

Full Mapping Workflow Example