Projects API — Create and Manage Mapping Projects

Projects are the core unit of collaborative mapping in Tasking Manager. Each project defines an area of interest divided into tasks, a mapping difficulty, permitted editors, and metadata such as a campaign and organization. The endpoints below cover the full project lifecycle — from creating a draft to publishing, monitoring activity, and archiving. All authenticated endpoints expect an Authorization: Token <session_token> header. Responses are JSON unless otherwise noted. The API base path is /api/v2.

Project CRUD

List and Search Projects

Authentication is optional. Unauthenticated requests return only published, public projects. Some filters (e.g., createdByMe, managedByMe) are silently ignored when no token is provided.

GET /api/v2/projects/ Returns a paginated list of projects matching the supplied filters. Supports ordering, filtering by mapping type, campaign, organisation, difficulty, status, country, and date ranges.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/?campaign=malaria&orderBy=priority&orderByType=ASC&page=1" \
  -H "Accept-Language: en"

Query Parameters

difficulty

string

Filter by project difficulty. Valid values: EASY, MODERATE, CHALLENGING.

action

string

Filter by possible user action. Valid values: map, validate, any.

mappingTypes

string

Comma-separated mapping types to filter by. Valid values: ROADS, BUILDINGS, WATERWAYS, LAND_USE, OTHER.

mappingTypesExact

boolean

default:"false"

When true, only projects that match all listed mapping types are returned.

organisationName

string

Filter by organisation name.

organisationId

integer

Filter by organisation ID.

campaign

string

Filter by campaign name.

teamId

integer

Filter by team membership on the project.

country

string

Filter by country name.

textSearch

string

Free-text search across project name and description.

projectStatuses

string

Comma-separated statuses. Valid values: DRAFT, PUBLISHED, ARCHIVED. Project managers can access DRAFT and ARCHIVED.

orderBy

string

default:"priority"

Sort field. Valid values: id, difficulty, priority, status, last_updated, due_date.

orderByType

string

default:"ASC"

Sort direction. Valid values: ASC, DESC.

page

integer

default:"1"

Page number (1-indexed).

omitMapResults

boolean

default:"false"

When true, omits project centroid geometries from the response, reducing payload size.

lastUpdatedFrom

string

ISO 8601 date. Return only projects last updated on or after this date.

lastUpdatedTo

string

ISO 8601 date. Return only projects last updated on or before this date.

createdFrom

string

ISO 8601 date. Return only projects created on or after this date.

createdTo

string

ISO 8601 date. Return only projects created on or before this date.

interests

string

Comma-separated interest IDs to filter projects by interest category.

createdByMe

boolean

default:"false"

Limit results to projects created by the authenticated user.

mappedByMe

boolean

default:"false"

Limit results to projects the authenticated user has contributed to.

favoritedByMe

boolean

default:"false"

Limit results to projects favorited by the authenticated user.

managedByMe

boolean

default:"false"

Limit results to projects manageable by the authenticated user (excluding those they created).

basedOnMyInterests

boolean

default:"false"

Filter projects based on the authenticated user’s recorded interests.

downloadAsCSV

boolean

When true, streams results as a CSV file instead of JSON. Cannot be combined with omitMapResults=true.

partnerId

integer

Filter by partner ID. Admin-only — requires authentication.

partnershipFrom

string

ISO 8601 date. Filter projects whose partnership started on or after this date. Requires partnerId.

partnershipTo

string

ISO 8601 date. Filter projects whose partnership ended on or before this date. Requires partnerId.

Responses

Status	Description
`200`	Projects found. Returns paginated results object or empty lists when none match.
`400`	Invalid query parameters or conflicting filter combination.
`500`	Internal server error.

Create a Project

POST /api/v2/projects/ Creates a new draft project. Requires the caller to be a Project Manager or Admin.

curl -X POST "https://tasking-manager-api.hotosm.org/api/v2/projects/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "Humanitarian Building Mapping - Nairobi",
    "organisation": 42,
    "areaOfInterest": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [[[36.8,-1.3],[36.9,-1.3],[36.9,-1.2],[36.8,-1.2],[36.8,-1.3]]]
          },
          "properties": {}
        }
      ]
    },
    "tasks": {
      "type": "FeatureCollection",
      "features": []
    },
    "arbitraryTasks": false
  }'

Request Body

projectName

string

required

Human-readable project name.

areaOfInterest

object

required

GeoJSON FeatureCollection defining the mapping boundary.

tasks

object

GeoJSON FeatureCollection of pre-defined task geometries. Leave empty or omit to use grid-based task generation.

arbitraryTasks

boolean

default:"false"

When true, tasks are not constrained to a grid.

organisation

integer

ID of the organisation this project belongs to.

cloneFromProjectId

integer

If provided, the new project clones settings from this existing project ID.

Responses

Status	Description
`201`	Draft project created. Body: `{"projectId": <int>}`
`400`	Invalid request body or GeoJSON.
`401`	Missing or invalid token.
`403`	User lacks Project Manager role.

Get a Project

GET /api/v2/projects/{project_id}/ Returns full project details including task grid, localized info, and mapping metadata. Authentication is optional; private or draft projects require a valid token and appropriate permissions.

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

Path Parameters

project_id

integer

required

Unique project ID.

Query Parameters

as_file

boolean

default:"false"

When true, returns the project as a downloadable JSON file attachment.

abbreviated

boolean

default:"false"

When true, returns only project status information (lightweight response).

Responses

Status	Description
`200`	Project found. Returns full `ProjectDTO` object.
`403`	User is not permitted to view this private or draft project.
`404`	Project not found.
`500`	Internal server error.

Update a Project

PATCH /api/v2/projects/{project_id}/ Updates an existing project. The caller must be a project manager or admin for this project. Requires a valid token.

curl -X PATCH "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "projectStatus": "PUBLISHED",
    "projectPriority": "HIGH",
    "difficulty": "MODERATE",
    "changesetComment": "#hotosm-project-1234",
    "mappingTypes": ["BUILDINGS"],
    "mappingEditors": ["ID", "JOSM"],
    "defaultLocale": "en"
  }'

Path Parameters

project_id

integer

required

Unique project ID.

Request Body

projectStatus

string

New project status. Valid values: DRAFT, PUBLISHED, ARCHIVED.

projectPriority

string

Priority level. Valid values: URGENT, HIGH, MEDIUM, LOW.

difficulty

string

Mapper skill level required. Valid values: EASY, MODERATE, CHALLENGING.

defaultLocale

string

Default locale code (e.g., en, fr).

changesetComment

string

OSM changeset comment prepended to mapper edits (e.g., #hotosm-project-1234).

mappingTypes

array

Array of mapping type strings. Valid values: ROADS, BUILDINGS, WATERWAYS, LAND_USE, OTHER.

mappingEditors

array

Editors allowed for mapping. Valid values: ID, JOSM, POTLATCH_2, FIELD_PAPERS, RAPID, CUSTOM.

validationEditors

array

Editors allowed for validation. Same values as mappingEditors.

private

boolean

When true, only explicitly allowed users can see and contribute.

dueDate

string

ISO 8601 datetime for the project’s target completion date.

imagery

string

Background imagery URL for mappers.

organisation

integer

Organisation ID for this project.

campaign

string

Campaign name to associate with this project.

countryTag

array

Array of country name strings for geographic tagging.

allowedUsernames

array

For private projects: list of OSM usernames who may access the project.

mapping_permission

string

Who can map. Valid values: ANY, TEAMS.

validation_permission

string

Who can validate. Valid values: ANY, TEAMS.

projectInfoLocales

array

Array of localized project info objects with fields locale, name, shortDescription, description, instructions, perTaskInstructions.

Responses

Status	Description
`200`	Project updated. Body: `{"Status": "Updated"}`
`400`	Invalid request body or GeoJSON.
`401`	Missing or invalid token.
`403`	User is not a project manager for this project.
`404`	Project not found.

Delete a Project

DELETE /api/v2/projects/{project_id}/ Permanently deletes a project. The caller must be a project manager or admin for this project.

Deletion is irreversible. All associated task data and history will be removed. Ensure you have confirmed with your team before proceeding.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Project deleted. Body: `{"Success": "Project deleted"}`
`401`	Missing or invalid token.
`403`	User does not have permission to delete this project.
`404`	Project not found.

Project Queries

Get Project Summary

GET /api/v2/projects/{project_id}/queries/summary/ Returns a lightweight summary of a project. Private or draft projects enforce authentication and permission checks.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Project summary returned.
`403`	User not permitted to view private or draft project.
`404`	Project not found.
`500`	Internal server error.

Get Featured Projects

GET /api/v2/projects/queries/featured/ Returns projects that have been marked as featured. No authentication required.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/queries/featured/" \
  -H "Accept-Language: en"

Responses

Status	Description
`200`	Featured projects returned.
`500`	Internal server error.

Get Projects by Bounding Box

GET /api/v2/projects/queries/bbox/ Returns projects whose area of interest intersects with the supplied bounding box. Requires a valid token and the user must manage at least one organisation.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/queries/bbox/?bbox=34.404,-1.034,34.717,-0.624&srid=4326" \
  -H "Authorization: Token sessionTokenHere=="

Query Parameters

bbox

string

required

Comma-separated bounding box coordinates: xmin,ymin,xmax,ymax.

srid

integer

default:"4326"

Spatial reference ID of the bbox coordinates.

createdByMe

boolean

default:"false"

Limit to projects created by the authenticated user.

Responses

Status	Description
`200`	Projects GeoJSON returned.
`400`	Invalid bounding box or bounding box too large.
`403`	User does not manage any organisation.
`500`	Internal server error.

Get Own Projects (Admin)

GET /api/v2/projects/queries/myself/owner/ Returns all projects managed by the authenticated user. The caller must manage at least one organisation.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/queries/myself/owner/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"

Responses

Status	Description
`200`	Projects returned.
`401`	Missing or invalid token.
`403`	User does not manage any organisation.
`404`	No projects found.
`500`	Internal server error.

Get Projects Touched by User

GET /api/v2/projects/queries/{username}/touched/ Returns projects that the specified user has mapped or validated.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/queries/Thinkwhere/touched/" \
  -H "Accept-Language: en"

Path Parameters

username

string

required

OSM username of the user.

Responses

Status	Description
`200`	Mapped projects returned.
`404`	User not found.
`500`	Internal server error.

Project Actions

Transfer Project Ownership

POST /api/v2/projects/{project_id}/actions/transfer-ownership/ Transfers ownership of a project to another user. The caller must be the current project manager or admin. Sends a notification to the new owner as a background task.

curl -X POST "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/actions/transfer-ownership/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{"username": "new_owner_username"}'

Path Parameters

project_id

integer

required

Unique project ID.

Request Body

username

string

required

OSM username of the user to transfer project ownership to.

Responses

Status	Description
`200`	Ownership transferred. Body: `{"Success": "Project Transferred"}`
`400`	Username not provided.
`401`	Missing or invalid token.
`403`	User is not authorized to transfer this project.

Message All Contributors

POST /api/v2/projects/{project_id}/actions/message-contributors/ Sends an in-platform message to every user who has contributed to the project. Runs as a background task — the response is immediate while messages are dispatched asynchronously. Requires project manager or admin role.

curl -X POST "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/actions/message-contributors/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Thank you for mapping!",
    "message": "Your contributions to project 1234 have helped us map 500 buildings."
  }'

Path Parameters

project_id

integer

required

Unique project ID.

Request Body

subject

string

required

Message subject line.

message

string

required

Message body text.

Responses

Status	Description
`200`	Messaging job started. Body: `{"Success": "Messages started"}`
`400`	Invalid request body.
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Background task failed to start.

Set Project as Featured

POST /api/v2/projects/{project_id}/actions/feature/ Marks a project as featured so it appears in the featured projects list. The caller must be a project manager or admin.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Project set as featured. Body: `{"Success": true}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`404`	Project not found.
`500`	Internal server error.

Remove Project from Featured

POST /api/v2/projects/{project_id}/actions/remove-feature/ Removes a project from the featured list. The caller must be a project manager or admin.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Project removed from featured. Body: `{"Success": true}`
`401`	Missing or invalid token.
`403`	User is not a project manager.
`404`	Project not found.
`500`	Internal server error.

Set Project Interests

POST /api/v2/projects/{project_id}/actions/set-interests/ Creates or replaces the interest associations for a project. The caller must be a project manager or admin.

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

Path Parameters

project_id

integer

required

Unique project ID.

Request Body

interests

array

required

Array of integer interest IDs to associate with the project.

Responses

Status	Description
`200`	Interests updated.
`400`	Invalid request.
`401`	Missing or invalid token.
`403`	User is not a project manager.
`500`	Internal server error.

Project Statistics

Get Project Statistics

GET /api/v2/projects/{project_id}/statistics/ Returns aggregated statistics for a project including counts of tasks by status (ready, mapped, validated, etc.) and contributor counts.

curl "https://tasking-manager-api.hotosm.org/api/v2/projects/1234/statistics/"

Path Parameters

project_id

integer

required

Unique project ID.

Response Fields

totalTasks

integer

Total number of tasks in the project.

totalMappedTasks

integer

Number of tasks in MAPPED status.

totalValidatedTasks

integer

Number of tasks in VALIDATED status.

totalReadyTasks

integer

Number of tasks in READY status.

totalInvalidatedTasks

integer

Number of tasks in INVALIDATED status.

totalBadImagery

integer

Number of tasks in BADIMAGERY status.

percentMapped

integer

Percentage of tasks that have been mapped.

percentValidated

integer

Percentage of tasks that have been validated.

Responses

Status	Description
`200`	Statistics returned.
`404`	Project not found.
`500`	Internal server error.

Get Project User Statistics

GET /api/v2/projects/{project_id}/statistics/queries/{username}/ Returns detailed statistics about a specific user’s contributions to the project.

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

Path Parameters

project_id

integer

required

Unique project ID.

username

string

required

OSM username to get statistics for.

Responses

Status	Description
`200`	User project statistics returned.
`404`	User or project not found.
`500`	Internal server error.

Get Project Activity Log

GET /api/v2/projects/{project_id}/activities/ Returns a paginated log of user mapping and validation activity events for a project, ordered by most recent first. Private or draft projects require authentication and appropriate permissions.

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

Path Parameters

project_id

integer

required

Unique project ID.

Query Parameters

page

integer

default:"1"

Page number for paginated results. Minimum value: 1.

Responses

Status	Description
`200`	Activity log returned.
`403`	User not permitted to view private/draft project.
`404`	No activity found.
`500`	Internal server error.

Favorites

Favorites allow authenticated users to bookmark projects they care about. Each endpoint operates on the authenticated user’s own favorites list.

Check Favorite Status

GET /api/v2/projects/{project_id}/favorite/ Returns whether the authenticated user has favorited the specified project. Requires a valid token.

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

Path Parameters

project_id

integer

required

Unique project ID.

Response Fields

favorited

boolean

true if the authenticated user has favorited this project, false otherwise.

Responses

Status	Description
`200`	Body: `{"favorited": true}` or `{"favorited": false}`
`401`	Missing or invalid token.

Add Favorite

POST /api/v2/projects/{project_id}/favorite/ Adds the specified project to the authenticated user’s favorites. Requires a valid token.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`201`	Favorite added. Body: `{"project_id": <int>}`
`401`	Missing or invalid token.
`500`	Internal server error.

Remove Favorite

DELETE /api/v2/projects/{project_id}/favorite/ Removes the specified project from the authenticated user’s favorites. Requires a valid token.

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

Path Parameters

project_id

integer

required

Unique project ID.

Responses

Status	Description
`200`	Favorite removed. Body: `{"project_id": <int>}`
`400`	Project was not in user’s favorites.
`401`	Missing or invalid token.

Overview

Resources

Documentation Index

​Project CRUD

​List and Search Projects

​Query Parameters

​Responses

​Create a Project

​Request Body

​Responses

​Get a Project

​Path Parameters

​Query Parameters

​Responses

​Update a Project

​Path Parameters

​Request Body

​Responses

​Delete a Project

​Path Parameters

​Responses

​Project Queries

​Get Project Summary

​Path Parameters

​Responses

​Get Featured Projects

​Responses

​Get Projects by Bounding Box

​Query Parameters

​Responses

​Get Own Projects (Admin)

​Responses

​Get Projects Touched by User

​Path Parameters

​Responses

​Project Actions

​Transfer Project Ownership

​Path Parameters

​Request Body

​Responses

​Message All Contributors

​Path Parameters

​Request Body

​Responses

​Set Project as Featured

​Path Parameters

​Responses

​Remove Project from Featured

​Path Parameters

​Responses

​Set Project Interests

​Path Parameters

​Request Body

​Responses

​Project Statistics

​Get Project Statistics

​Path Parameters

​Response Fields

​Responses

​Get Project User Statistics

​Path Parameters

​Responses

​Get Project Activity Log

​Path Parameters

​Query Parameters

​Responses

​Favorites

​Check Favorite Status

​Path Parameters

​Response Fields

​Responses

​Add Favorite

​Path Parameters

​Responses

​Remove Favorite

​Path Parameters

​Responses

Build docs developers (and LLMs) love

Project CRUD

List and Search Projects

Query Parameters

Responses

Create a Project

Request Body

Responses

Get a Project

Path Parameters

Query Parameters

Responses

Update a Project

Path Parameters

Request Body

Responses

Delete a Project

Path Parameters

Responses

Project Queries

Get Project Summary

Path Parameters

Responses

Get Featured Projects

Responses

Get Projects by Bounding Box

Query Parameters

Responses

Get Own Projects (Admin)

Responses

Get Projects Touched by User

Path Parameters

Responses

Project Actions

Transfer Project Ownership

Path Parameters

Request Body

Responses

Message All Contributors

Path Parameters

Request Body

Responses

Set Project as Featured

Path Parameters

Responses

Remove Project from Featured

Path Parameters

Responses

Set Project Interests

Path Parameters

Request Body

Responses

Project Statistics

Get Project Statistics

Path Parameters

Response Fields

Responses

Get Project User Statistics

Path Parameters

Responses

Get Project Activity Log

Path Parameters

Query Parameters

Responses

Favorites

Check Favorite Status

Path Parameters

Response Fields

Responses

Add Favorite

Path Parameters

Responses

Remove Favorite

Path Parameters

Responses