REST API reference

The machine-readable contract is /api/v1/openapi.json (OpenAPI 3.1): load it into Postman, Insomnia or a client generator. This page is generated from it. To make your first call, see Use the REST API.

Base URL https://mapsurvey.org/api/v1 · Authentication Authorization: Bearer <token> — a personal token or an OAuth 2.1 access token · Plan the workspace that owns the survey must be on Pro.

Errors

Every error has the same shape: {"error": "<code>", "detail": "<text>", ...}. Switch on error; detail is for people and may change. validation errors add fields (field name → messages), and an unknown field in a request body is refused by name rather than ignored.

Code	Status	Meaning
invalid_token	401	No bearer token, or one that is unknown, expired or revoked.
scope_missing	403	The token lacks the permission this call needs (scope names it).
pro_required	403	The survey’s workspace is not on Pro (upgrade_url links to its billing page).
forbidden_role	403	You can see the survey but your role on it is too low (role names the one needed).
not_found	404	Nothing there — or nothing you may see. The two are deliberately the same answer.
validation	422	The body or a parameter is invalid; fields lists what and why.
draft_required	409	A structural change to a live survey: start unpublished changes (draft is their uuid when they exist).
answers_at_risk	409	The delete would remove count answers; repeat with acknowledge_answer_loss=true.
delete_blocked	409	Something else depends on what you are deleting.
translation_gaps	409	Some languages are missing text; repeat with acknowledge_translation_gaps: true.
incompatible_draft	409	Unpublished changes conflict with collected answers; repeat with force: true.
transition_refused	409	The survey cannot move to that status from where it is.
email_unconfirmed	403	The account has not confirmed its email address yet; publishing waits for it.
conflict	409	The request conflicts with the current state (e.g. unpublished changes already exist).
bad_cursor	400	The pagination cursor is not valid for this list.
method_not_allowed	405	That HTTP method is not offered on this path (Allow lists the ones that are).
rate_limited	429	Too many calls; wait Retry-After seconds.
server_error	500	Our fault. It is logged; retrying later is safe for reads.

Account

GET /me

The token’s user, its workspaces with their plan and whether the API is included, and the token’s kind, scopes, audiences, binding and expiry.

200 MeOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Import

POST /surveys/import

Import a survey ZIP (the editor’s “Backup (survey file)”) as a job. Poll /import-jobs/{id} until status is done or failed.

Body

Field	Type	Required	Notes
file	binary	yes
workspace	string or null

202 ImportJobOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /import-jobs/{job_id}

One of your import jobs.

Parameter	In	Type	Required
job_id	path	integer	yes

200 ImportJobOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Surveys

GET /surveys

Your surveys across the workspaces whose plan includes the API, newest first.

Parameter	In	Type	Required
cursor	query	string or null
limit	query	integer

200 SurveyList

Errors: bad_cursor, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys

A new empty survey with one section, owned by you.

Body

Field	Type	Required	Notes
name	string	yes
workspace	string or null		Workspace slug; optional when the token is bound to one or you belong to one.
language	string
map_start	MapStart or null

201 SurveyDetailOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}

Get Survey

Parameter	In	Type	Required
uuid	path	uuid	yes

200 SurveyDetailOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}

Settings, the thanks page and the map start. Settings and the map need the owner role, like the editor; the thanks page the editor role.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
name	string or null
redirect_url	string or null		“#” for the built-in thanks page, or an absolute http(s) URL.
languages	list of string or null
visibility	public	private	demo or null
basemaps	list of string or null		Preset keys (streets, satellite, topo, paper, paper_b) or “style:” of a workspace map style; a key the workspace does not have is dropped.
default_basemap	string or null		One of basemaps; else the first enabled key.
show_branding	boolean or null
thanks_html	object or null		Thanks page per language; creator HTML, sanitised on save.
map_start	MapStart or null
use_geolocation	boolean or null
opens_at	date-time or null		Start of the survey period: ISO 8601 with an offset, or a naive value read in schedule_timezone. Null clears it.
closes_at	date-time or null		End of the survey period, after the start and in the future. Null clears it. Reopening a survey by hand clears a past end.
schedule_timezone	string or null		IANA zone (e.g. “Europe/Berlin”) naive period values are read in and times are shown in; “” = UTC.

200 SurveyDetailOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}

Move the survey to the trash; it can be restored in the editor for 30 days.

Parameter	In	Type	Required
uuid	path	uuid	yes

204 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/publish

Publish. review: "pending" means content screening is holding the survey: respondents see an unavailable page until it is reviewed.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 SurveyOut

Errors: conflict, draft_required, email_unconfirmed, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, transition_refused, translation_gaps, validation

POST /surveys/{uuid}/close

Stop collecting answers; the survey stays readable to you.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 SurveyOut

Errors: conflict, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, transition_refused, validation

POST /surveys/{uuid}/draft

Start unpublished changes on a published or closed survey. Edit the returned uuid; respondents keep the live survey until you publish them.

Parameter	In	Type	Required
uuid	path	uuid	yes

201 SurveyOut

Errors: conflict, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, transition_refused, validation

DELETE /surveys/{uuid}/draft

Throw the unpublished changes away; the live survey is untouched.

Parameter	In	Type	Required
uuid	path	uuid	yes

204 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/draft/publish

Publish the unpublished changes as a new version of the live survey.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 SurveyOut

Errors: conflict, draft_required, email_unconfirmed, forbidden_role, incompatible_draft, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, translation_gaps, validation

Structure

GET /surveys/{uuid}/sections/{section_id}/groups

The section’s question groups – top level first, then each pop-up’s – in order.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

200 list of GroupOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections/{section_id}/groups

A group at the end of the section (or of a pop-up with parent_id); question_ids fills it.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

Body

Field	Type	Required	Notes
title	string or null
description	string or null
display_style	plain	card	collapsible or null
budget	BudgetSettingsIn or null		Makes the group a budget: its map questions carry a price and respondents place marks until the total is spent (total, unit, symbol). Null removes the budget.
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
translations	object or null
question_ids	list of integer or null		The questions the group holds, in order; they move together to where the first of them was. Questions of the same list only (the section, or the same pop-up).
parent_id	integer or null		Create the group in this question’s pop-up.

201 GroupOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/groups/{group_id}

Get Group

Parameter	In	Type	Required
uuid	path	uuid	yes
group_id	path	integer	yes

200 GroupOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/groups/{group_id}

Wording and style apply to a live survey in place; the rule and question_ids are structure.

Parameter	In	Type	Required
uuid	path	uuid	yes
group_id	path	integer	yes

Body

Field	Type	Required	Notes
title	string or null
description	string or null
display_style	plain	card	collapsible or null
budget	BudgetSettingsIn or null		Makes the group a budget: its map questions carry a price and respondents place marks until the total is spent (total, unit, symbol). Null removes the budget.
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
translations	object or null
question_ids	list of integer or null		The questions the group holds, in order; they move together to where the first of them was. Questions of the same list only (the section, or the same pop-up).

200 GroupOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/groups/{group_id}

Delete the group; its questions stay in place, ungrouped, unless with_questions.

Parameter	In	Type	Required
uuid	path	uuid	yes
group_id	path	integer	yes
with_questions	query	boolean
acknowledge_answer_loss	query	boolean

204 no body

Errors: answers_at_risk, delete_blocked, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/questions/{question_id}/duplicate

A copy right after the question, in its group, with “ (copy)” on the name and its sub-questions.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

201 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections/{section_id}/duplicate

A copy of the section with all its questions, right after it, “ (copy)” on the title.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

201 SectionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections/{section_id}/questions/copy

Append a copy of a question from any survey you can read (new codes, its own files).

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

Body

Field	Type	Required	Notes
source_question_id	integer	yes	A question of any survey you can read.
parent_id	integer or null		Paste into this question’s pop-up (without the source’s own sub-questions).

201 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections/copy

Append a copy of a section from any survey you can read.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
source_section_id	integer	yes	A section of any survey you can read.

201 SectionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/questions/{question_id}/move

Move a question to another section, into a pop-up or out of one, to position.

Between sections it keeps its answers and leaves its group. Into or out of a pop-up its answers cannot follow (one per respondent against one per mark): 409 answers_at_risk until acknowledge_answer_loss. Rules the move breaks are cleared and named in removed_rules.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

Body

Field	Type	Required	Notes
section_id	integer or null		Target section of the same survey; default: its own.
parent_id	integer or null		Move into this question’s pop-up; null moves it to the section’s top level.
position	integer or null		Place among the target list’s items (a group counts as one); default: the end.
acknowledge_answer_loss	boolean

200 MoveOut

Errors: answers_at_risk, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/duplicate

A new draft survey in the same workspace with this one’s sections, questions, groups, rules, translations, settings and map layers – no responses, versions, links or public results page.

Parameter	In	Type	Required
uuid	path	uuid	yes

201 DuplicateSurveyOut

Errors: draft_required, forbidden_role, invalid_token, limit_reached, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/versions

The current survey, then its archived versions newest first; each publish makes a version.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 list of VersionOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/versions/{version}/restore

Unpublished changes holding version version’s questionnaire. The live survey is unchanged until you publish them, which makes a NEW version; history is never rewritten.

Parameter	In	Type	Required
uuid	path	uuid	yes
version	path	integer	yes

201 RestoreOut

Errors: conflict, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, transition_refused, validation

GET /icons

Marker icons by meaning, best first: every word must match the icon’s name, label or search terms in lang (default: your interface language) or English. set narrows to maki, temaki or fa. Every value is accepted as icon_class.

Parameter	In	Type	Required
q	query	string
lang	query	string or null
set	query	string or null
limit	query	integer

200 list of IconOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Sections

GET /surveys/{uuid}/sections

The survey’s sections in respondent order.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 list of SectionOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections

Append a section; the body sets its fields at once.

Parameter	In	Type	Required
uuid	path	uuid	yes

201 SectionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PUT /surveys/{uuid}/sections/order

The new order; list every section exactly once. (Declared before the {section_id} routes: ninja matches that segment as a string.)

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
section_ids	list of integer	yes

200 list of SectionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/sections/{section_id}

Get Section

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

200 SectionOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/sections/{section_id}

Change the fields the body names. On a live survey wording is applied in place; the code and the visibility rule are structure (409 draft_required).

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

Body

Field	Type	Required	Notes
title	string or null
subheading	string or null
code	string or null
layout	map	image	form or null
panel_side	left	right or null
panel_width	default	third	half or null
content_width	full	column or null
content_valign	top	middle or null
keep_panel_open	boolean or null
next_label	string or null
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
translations	object or null
map_start	MapStart or null
use_geolocation	boolean or null

200 SectionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/sections/{section_id}

Delete a section with its questions. Answers to them go too: the first call answers 409 answers_at_risk with the count; repeat with acknowledge_answer_loss=true.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes
acknowledge_answer_loss	query	boolean

204 no body

Errors: answers_at_risk, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Questions

GET /surveys/{uuid}/sections/{section_id}/questions

Top-level questions of a section in order; each lists its sub-question ids.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

200 list of QuestionOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/sections/{section_id}/questions

Add a question at the end of the section.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

Body

Field	Type	Required	Notes
name	string or null
subtext	string or null
input_type	text	number	choice
required	boolean or null
choices	list of ChoiceIn or null
validation_settings	ValidationSettingsIn or null
budget	BudgetSettingsIn or null		Settings of a budget question.
price	PriceIn or null		A map question’s price under a budget group; null removes it.
color	string or null
icon_class	string or null
display_style	string or null
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
layer_id	integer or null
layer_from_answers	string or null		For an “Objects on the map” question: the code of a map question whose answers become a shared map (created on first use). Use instead of layer_id.
min_objects	integer or null
share_with_respondents	boolean or null
translations	object or null

201 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PUT /surveys/{uuid}/sections/{section_id}/questions/order

Renumber the section’s top level (or one pop-up, with parent_id). Items are question ids, or {"g": <group id>, "q": [<ids>]} for a group.

Parameter	In	Type	Required
uuid	path	uuid	yes
section_id	path	integer	yes

Body

Field	Type	Required	Notes
parent_id	integer or null		Order a pop-up’s sub-questions instead of the section’s top level.
items	list of integer or object	yes	Question ids in order; a group is {“g”: , “q”: []}.

200 list of QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/questions/{question_id}

Get Question

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

200 QuestionOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/questions/{question_id}

Change the fields the body names. On a live survey wording, help text, translations and added options are applied in place; type, layer, visibility rule and removing an answered option are structure (409 draft_required). validation_settings replaces the whole object.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

Body

Field	Type	Required	Notes
name	string or null
subtext	string or null
input_type	text	number	choice
required	boolean or null
choices	list of ChoiceIn or null
validation_settings	ValidationSettingsIn or null
budget	BudgetSettingsIn or null		Settings of a budget question.
price	PriceIn or null		A map question’s price under a budget group; null removes it.
color	string or null
icon_class	string or null
display_style	string or null
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
layer_id	integer or null
layer_from_answers	string or null		For an “Objects on the map” question: the code of a map question whose answers become a shared map (created on first use). Use instead of layer_id.
min_objects	integer or null
share_with_respondents	boolean or null
translations	object or null

200 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/questions/{question_id}

Delete a question with its sub-questions; see acknowledge_answer_loss on section delete.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes
acknowledge_answer_loss	query	boolean

204 no body

Errors: answers_at_risk, delete_blocked, draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PUT /surveys/{uuid}/questions/{question_id}/choices

Replace the options of a choice question. Keep an option’s code to keep its answers; a new option gets a code never used in the survey’s history.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

Body

Field	Type	Required	Notes
choices	list of ChoiceIn	yes

200 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/questions/{question_id}/subquestions

Ask something about each feature placed on a geo question, or each object of an Objects question: the sub-question appears in its pop-up.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes

Body

Field	Type	Required	Notes
name	string or null
subtext	string or null
input_type	text	number	choice
required	boolean or null
choices	list of ChoiceIn or null
validation_settings	ValidationSettingsIn or null
budget	BudgetSettingsIn or null		Settings of a budget question.
price	PriceIn or null		A map question’s price under a budget group; null removes it.
color	string or null
icon_class	string or null
display_style	string or null
visibility_rule	VisibilityRule or null
audience	everyone	respondents	operators or null
layer_id	integer or null
layer_from_answers	string or null		For an “Objects on the map” question: the code of a map question whose answers become a shared map (created on first use). Use instead of layer_id.
min_objects	integer or null
share_with_respondents	boolean or null
translations	object or null

201 QuestionOut

Errors: draft_required, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Layers

GET /surveys/{uuid}/layers

The survey’s reference layers, metadata only; fetch geometry from geojson_url.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 list of LayerOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/layers

A layer from GeoJSON in the body (or an empty one). Owner role; at most 10 layers per survey.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
name	string or null
geojson	object or null		A FeatureCollection, a Feature or a bare geometry in WGS 84 (lng, lat). At most 10 MB and 5 000 features; multi-part geometries become one object per part. Omit for an empty layer.

201 object

Errors: forbidden_role, invalid_token, limit_reached, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/layers/upload

A layer from a GeoJSON file (multipart). Owner role.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
file	binary	yes
name	string or null

201 object

Errors: forbidden_role, invalid_token, limit_reached, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PUT /surveys/{uuid}/layers/order

Set the layers’ order (map stacking and the Layers panel). Owner role.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
layer_ids	list of integer	yes	Every layer id of the survey, in the new order.

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/layers/{layer_id}

Name, color, label/key field, popups and style – never geometry. Owner role.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes

Body

Field	Type	Required	Notes
name	string or null
color	string or null		#rrggbb
label_field	string or null		A property shown as the object title on the map.
key_field	string or null
show_popups	boolean or null
style	object or null		opacity, weight, fill_opacity, radius, icon, legend, and by — one rule on one property (categories or graduated classes). Normalised on save.

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/layers/{layer_id}

Delete a layer and its objects – refused while a question uses it. Owner role.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes

200 no body

Errors: conflict, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/layers/{layer_id}/objects

The layer’s objects with geometry and properties, paged.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes
cursor	query	string or null
limit	query	integer

200 no body

Errors: bad_cursor, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/layers/{layer_id}/objects

Add an object. Owner role; not on a shared-map layer.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes

Body

Field	Type	Required	Notes
key	string or null		Unique in the layer; generated when omitted.
title	string or null
category	string or null
description	string or null		Rich text; sanitised like every creator text.
link	string or null		An http:// or https:// address.
geometry	object	yes
properties	object or null

201 object

Errors: conflict, forbidden_role, invalid_token, limit_reached, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/layers/{layer_id}/objects/{key}

Get Object

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes
key	path	string	yes

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/layers/{layer_id}/objects/{key}

Change an object’s text, link, geometry or properties. The key cannot change. Owner role.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes
key	path	string	yes

Body

Field	Type	Required	Notes
key	string or null		Unique in the layer; generated when omitted.
title	string or null
category	string or null
description	string or null		Rich text; sanitised like every creator text.
link	string or null		An http:// or https:// address.
geometry	object or null		One Point, LineString or Polygon (WGS 84).
properties	object or null

200 no body

Errors: conflict, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/layers/{layer_id}/objects/{key}

Delete Object

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes
key	path	string	yes

200 no body

Errors: conflict, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/layers/{layer_id}/objects/{key}/status

Moderate a mark on a shared map: visible, pending or hidden. Editor role.

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes
key	path	string	yes

Body

Field	Type	Required	Notes
status	string	yes	visible, pending or hidden.

200 no body

Errors: conflict, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Data

GET /surveys/{uuid}/layers/{layer_id}/geojson

The layer’s GeoJSON FeatureCollection. Sent gzip-encoded to a client that accepts it (the stored bytes, passed through).

Parameter	In	Type	Required
uuid	path	uuid	yes
layer_id	path	integer	yes

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/responses

Responses of every version of the survey, newest first. Sessions that answered nothing are left out unless include_empty=true. Answers carry no respondent IP or browser.

Parameter	In	Type	Required
uuid	path	uuid	yes
include_empty	query	boolean
cursor	query	string or null
limit	query	integer

200 ResponseList

Errors: bad_cursor, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/export

The Responses page’s “Export data” as a file: zip (GeoJSON + CSV), xlsx, csv, gpkg, shp, kml; files=true adds uploads.

Parameter	In	Type	Required
uuid	path	uuid	yes
format	query	string
version	query	string or null
include_all	query	boolean
completed_only	query	boolean
files	query	boolean

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Responses

GET /surveys/{uuid}/responses/summary

Counts and per-question statistics over the sessions the export of the same parameters contains: no empty, deleted or rejected responses unless include_all. Sub-questions of map questions are nested under them.

Parameter	In	Type	Required
uuid	path	uuid	yes
version	query	string or null
include_all	query	boolean
completed_only	query	boolean

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/questions/{question_id}/answers

Non-blank answers to one text question (or text sub-question), newest first.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes
version	query	string or null
include_all	query	boolean
completed_only	query	boolean
cursor	query	string or null
limit	query	integer

200 no body

Errors: bad_cursor, forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/questions/{question_id}/geojson

One map question’s answers as a CRS84 FeatureCollection, sub-question values as properties – the export’s GeoJSON layer. Stops at 5 000 features (truncated: true); the full set is the export.

Parameter	In	Type	Required
uuid	path	uuid	yes
question_id	path	integer	yes
version	query	string or null
include_all	query	boolean
completed_only	query	boolean

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/export-link

A link to the export file, valid 15 minutes, for a person to open. Opening it checks again that you may read the survey and that its workspace is on Pro.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
format	zip	xlsx	csv
version	string or null		One version (v3), several separated by commas (v10,v11), or omit for every version.
include_all	boolean		Also deleted and rejected responses.
completed_only	boolean		Only responses that reached the last section.
files	boolean		Add uploaded files (turns a single-file format into a ZIP).

200 ExportLinkOut

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PATCH /surveys/{uuid}/responses/{response_id}

Approve, hold or reject a response ("" clears the status). Rejected responses leave exports, summaries and public results; shared-map layers are rebuilt. Needs the editor role.

Parameter	In	Type	Required
uuid	path	uuid	yes
response_id	path	integer	yes

Body

Field	Type	Required	Notes
validation_status	approved	not_approved	on_hold

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Share

GET /surveys/{uuid}/share

How to send the survey out: its link, the public results link, the embed snippet and allowed hosts – once it is published (shareable). In testing, editors also get the test link with its token.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/share/qr.{fmt}

A QR code of the survey link (or of tracked link link) for posters and flyers. size is pixels per module, 1-40.

Parameter	In	Type	Required
uuid	path	uuid	yes
fmt	path	svg	png
size	query	integer
link	query	integer or null

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, not_shareable, pro_required, rate_limited, scope_missing, server_error, validation

GET /surveys/{uuid}/tracked-links

Campaign links – the survey link with UTM parameters – with how many responses started and completed through each.

Parameter	In	Type	Required
uuid	path	uuid	yes

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

POST /surveys/{uuid}/tracked-links

Add a campaign link (editor role). At most 200 per survey.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
utm_source	string	yes	Where the link is posted, e.g. “newsletter”.
utm_medium	string		e.g. “email”, “poster”, “social”.
utm_campaign	string		e.g. “spring-2027”.

200 no body

Errors: forbidden_role, invalid_token, limit_reached, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

DELETE /surveys/{uuid}/tracked-links/{link_id}

Remove a campaign link (editor role). Responses that came through it keep their source.

Parameter	In	Type	Required
uuid	path	uuid	yes
link_id	path	integer	yes

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

PUT /surveys/{uuid}/share/embed-hosts

Which sites may embed the survey (editor role); an empty list lets any site.

Parameter	In	Type	Required
uuid	path	uuid	yes

Body

Field	Type	Required	Notes
hosts	list of string	yes	Sites allowed to embed the survey, e.g. [“example.org”, “*.city.gov”]; empty = any site.

200 no body

Errors: forbidden_role, invalid_token, method_not_allowed, not_found, pro_required, rate_limited, scope_missing, server_error, validation

Objects

DuplicateSurveyOut

Field	Type	Always	Notes
uuid	uuid	yes
name	string	yes
status	string	yes
workspace	string or null	yes
languages	list of string	yes
redirect_url	string	yes
visibility	string	yes
version	integer	yes
is_unpublished_changes	boolean	yes
live_survey	uuid or null		For unpublished changes: the live survey they replace.
unpublished_changes	uuid or null		The uuid of this survey’s unpublished changes, if any.
review	pending or null		“pending” while content screening holds the survey.
opens_at	date-time or null		Start of the survey period (UTC): before it respondents see an “opens on” page. Null = no start.
closes_at	date-time or null		End of the survey period (UTC): the survey closes by itself then. Null = no end.
schedule_timezone	string		IANA zone the period was entered in; “” = UTC.
url	string	yes
created_at	date-time	yes
updated_at	date-time	yes
sections	integer	yes
questions	integer	yes
layers	integer	yes

ExportLinkOut

Field	Type	Always	Notes
url	string	yes	Open within 15 minutes; it checks your access again.
expires_at	date-time	yes

GroupOut

Field	Type	Always	Notes
id	integer	yes
code	string	yes
section_id	integer	yes
parent_id	integer or null		The question whose pop-up holds the group; null at top level.
order	integer	yes
title	string	yes
description	string	yes
display_style	plain	card	collapsible
budget	object or null	yes
visibility_rule	object or null	yes
audience	everyone	respondents	operators
question_ids	list of integer	yes
translations	object	yes

IconOut

Field	Type	Always	Notes
value	string	yes	The value to put in a question’s icon_class or a choice’s icon.
label	string	yes
set	maki	temaki	fa
categories	list of string	yes

ImportJobOut

Field	Type	Always	Notes
id	integer	yes
status	string	yes
original_name	string	yes
survey	uuid or null	yes
warnings	list of string	yes
error	string or null	yes
created_at	date-time	yes
finished_at	date-time or null	yes

LayerOut

Field	Type	Always	Notes
id	integer	yes
name	string	yes
source	string	yes
color	string or null	yes
position	integer	yes
feature_count	integer or null
property_names	list of string	yes
geojson_url	string	yes

MeOut

Field	Type	Always	Notes
user	MeUser	yes
workspaces	list of MeWorkspace	yes
token	MeToken	yes

MoveOut

Field	Type	Always	Notes
question	QuestionOut	yes
removed_rules	list of string	yes	Visibility rules the move broke and cleared, by their host’s label.

QuestionOut

Field	Type	Always	Notes
id	integer	yes
code	string or null	yes
section_id	integer	yes
parent_id	integer or null	yes
group_id	integer or null	yes
order	integer	yes
name	string	yes
subtext	string or null	yes
input_type	string	yes
required	boolean	yes
choices	list of object or null	yes
validation_settings	object	yes
color	string or null	yes
icon_class	string or null	yes
display_style	string or null	yes
visibility_rule	object or null	yes
audience	everyone	respondents	operators
layer_id	integer or null	yes
min_objects	integer or null	yes
share_with_respondents	boolean	yes
translations	object	yes
subquestions	list of integer	yes

ResponseList

Field	Type	Always	Notes
next_cursor	string or null
items	list of ResponseOut	yes

ResponseOut

Field	Type	Always	Notes
id	integer	yes
number	integer or null		The “#N” the Responses page shows; empty sessions have none.
survey	uuid	yes
started_at	date-time or null	yes
language	string or null	yes
validation_status	string	yes
answers	list of object	yes

RestoreOut

Field	Type	Always	Notes
unpublished_changes	uuid	yes
version	integer	yes

SectionOut

Field	Type	Always	Notes
id	integer	yes
code	string	yes
name	string	yes
title	string or null	yes
subheading	string or null	yes
layout	string	yes
panel_side	string	yes
panel_width	string	yes
content_width	string	yes
content_valign	string	yes
keep_panel_open	boolean	yes
stage_image	string or null	yes	URL of the picture an image section shows; null = the survey cover. Upload it in the editor.
next_label	string or null	yes
position	integer	yes
visibility_rule	object or null	yes
audience	everyone	respondents	operators
map_start	MapStart or null	yes
use_geolocation	boolean	yes
translations	object	yes
questions	list of integer	yes
groups	list of integer	yes	Question groups of the section, top level and pop-ups (GET …/groups).

SurveyDetailOut

Field	Type	Always	Notes
uuid	uuid	yes
name	string	yes
status	string	yes
workspace	string or null	yes
languages	list of string	yes
redirect_url	string	yes
visibility	string	yes
version	integer	yes
is_unpublished_changes	boolean	yes
live_survey	uuid or null		For unpublished changes: the live survey they replace.
unpublished_changes	uuid or null		The uuid of this survey’s unpublished changes, if any.
review	pending or null		“pending” while content screening holds the survey.
opens_at	date-time or null		Start of the survey period (UTC): before it respondents see an “opens on” page. Null = no start.
closes_at	date-time or null		End of the survey period (UTC): the survey closes by itself then. Null = no end.
schedule_timezone	string		IANA zone the period was entered in; “” = UTC.
url	string	yes
created_at	date-time	yes
updated_at	date-time	yes
thanks_html	object	yes
basemaps	list of string	yes	Base maps respondents may switch between: preset keys (streets, satellite, topo, paper, paper_b) or “style:” of a workspace map style.
default_basemap	string	yes	The base map the survey opens on; one of basemaps.
show_branding	boolean	yes
map_start	MapStart or null	yes
use_geolocation	boolean	yes
sections	list of integer	yes

SurveyList

Field	Type	Always	Notes
next_cursor	string or null
items	list of SurveyOut	yes
hidden_by_plan	integer		Workspaces of yours whose surveys are hidden: they are on the Free plan.

SurveyOut

Field	Type	Always	Notes
uuid	uuid	yes
name	string	yes
status	string	yes
workspace	string or null	yes
languages	list of string	yes
redirect_url	string	yes
visibility	string	yes
version	integer	yes
is_unpublished_changes	boolean	yes
live_survey	uuid or null		For unpublished changes: the live survey they replace.
unpublished_changes	uuid or null		The uuid of this survey’s unpublished changes, if any.
review	pending or null		“pending” while content screening holds the survey.
opens_at	date-time or null		Start of the survey period (UTC): before it respondents see an “opens on” page. Null = no start.
closes_at	date-time or null		End of the survey period (UTC): the survey closes by itself then. Null = no end.
schedule_timezone	string		IANA zone the period was entered in; “” = UTC.
url	string	yes
created_at	date-time	yes
updated_at	date-time	yes

VersionOut

Field	Type	Always	Notes
version	integer	yes
current	boolean	yes
status	string	yes
published_at	date-time or null	yes
sections	integer	yes
questions	integer	yes
responses	integer	yes