API Endpoints¶

This page lists the most relevant application endpoints used by UI workflows.

Map APIs¶

Endpoint	Method	Auth	Purpose
/parcels/api/geojson/	GET	login	Map data (grid summaries or parcel features, supports ref_ts)
/parcels/api/extent/	GET	login	Bounding extent of visible parcels (supports ref_ts)
/parcels/api/geojson/<uuid:pk>/	GET	login	Single parcel version-row GeoJSON detail
/parcels/api/select/	POST	login	Shape + predicate based selection
/parcels/api/inline-update/<uuid:pk>/	POST	staff	Inline map edit that creates a new parcel version
/api/rasters/	GET	login	Active/ready DEM and landcover overlay catalog for map settings
/api/rasters/sample/	GET	login	Raster point sample at lat/lng for selected slug values (samples[] response)
/raster-tiles/<path>	GET	login	Raster tile endpoint backed by persistent RASTER_TILES_ROOT

Parcel Snapping APIs¶

Endpoint	Method	Minimum role	Purpose
/parcels/api/map-settings/snapping/	GET	authenticated user	Lazily create and return the current user's complete versioned settings
/parcels/api/map-settings/snapping/	PUT	authenticated user	Atomically replace the current user's complete settings; user IDs and unknown fields are rejected
/parcels/api/snapping/candidate/	POST	exact active-dataset Editor	Canonicalize one selected target vertex or edge position against current official geometry
/parcels/api/snapping/trace/	POST	exact active-dataset Editor	Return both authoritative exterior-ring directions between compatible anchors

Candidate and trace requests accept transient EPSG:4326 JSON points/references, not geometry files. PostGIS transforms them to the frozen projected parcel CRS for extraction, distance, fraction, path, and length work. Responses contain display coordinates only.

Stable errors are snapping_validation_error (400), snapping_permission_denied (403), scoped snapping_target_not_found (404), and snapping_target_stale (409). Inaccessible targets do not return parcel labels or geometry.

Parcel Overlap Advisory API¶

Endpoint	Method	Scope	Purpose
/parcels/api/overlap-check/	POST	authenticated subject access plus exact Editor	Transform WGS84 proposal polygons to storage CRS and return versioned, read-only conflict evidence

The server derives the dataset, stable parcel identity, and declared sources from fresh_create, parcel, or draft subject context. It rejects client dataset or source substitution. Responses include safe target labels, square-metre areas, WGS84 intersection geometry, complete counts, and at most 500 issue objects.

List/Search/Selection APIs¶

Endpoint	Method	Auth	Purpose
/parcels/search/ajax/	GET	login	Autocomplete search
/parcels/api/filtered-ids/	GET	login	IDs of full filtered result set
/parcels/batch/	POST	login	Batch export/delete/group edit (effective_at supported for write actions)

Dataset Selector APIs¶

Endpoint	Method	Auth	Purpose
/auth/profile/set-active-dataset/	POST	login	Validate + set user active dataset, then redirect to safe next/referrer
/auth/api/datasets/accessible/	GET	login	List active datasets accessible to current user with effective role
/api/datasets/accessible/	GET	login	Root alias of accessible-datasets API for UI integrations

Upload and Analytics APIs¶

Endpoint	Method	Auth	Purpose
/parcels/upload/	GET/POST	login	Upload/analyze vector data
/parcels/upload/<uuid:pk>/preview/	GET/POST	login	Preview + apply upload decision
/parcels/api/statistics/	POST	internal/staff	Statistics data for ECharts dashboard

Export/Download Endpoints¶

Endpoint	Method	Auth	Purpose
/parcels/download/	GET	login	Download visible parcels in GIS formats
/parcels/export/?format=csv|geojson	GET	internal/staff	Legacy export helpers

Parcel Topology Change Requests¶

All topology endpoints require login and dataset-scoped visibility. Inaccessible request and parcel identifiers return 404 without disclosing existence. Mutation endpoints require the exact role for the current state and authorize before detailed file or geometry validation. Stable authorization failures use 403, stale/invalid states use 409, and authorized validation failures use 400.

Endpoint	Method	Minimum role	Purpose
/parcels/api/change-requests/	GET	Viewer	List visible split and merge requests
/parcels/api/change-requests/	POST	Editor	Create a grouped request using operation_type, source_ids, and merge primary_source_id
/parcels/api/change-requests/<request_id>/	GET	Viewer	Return canonical sources, saved split line, outputs, projected areas, validation, events, lineage, and permitted actions
/parcels/api/change-requests/<request_id>/split-line/	PUT	Editor	Transform one display line to the storage CRS and atomically generate exactly two PostGIS split outputs
/parcels/api/change-requests/<request_id>/outputs/	PATCH	Editor	Update output identifiers and eligible business attributes; geometry keys are rejected
/parcels/api/change-requests/<request_id>/output-import/	POST	Editor	Import multipart .gpkg or .zip output geometry with a declared projected CRS and known linear units
/parcels/api/change-requests/<uuid>/actions/validate/	POST	Editor	Run authoritative PostGIS validation
/parcels/api/change-requests/<uuid>/actions/submit/	POST	Editor	Validate and submit the complete grouped request
/parcels/api/change-requests/<uuid>/actions/review-accept/	POST	Reviewer	Accept a submitted request for approval
/parcels/api/change-requests/<uuid>/actions/final-approve/	POST	Approver	Atomically retire sources, create results, transaction, and lineage
/parcels/api/change-requests/<uuid>/actions/reject/	POST	Reviewer/Approver	Reject with a required reason
/parcels/api/change-requests/<uuid>/actions/cancel/	POST	State-dependent	Cancel an uncommitted request
/parcels/api/change-requests/<uuid>/events/	GET	Viewer	Return scoped workflow-event history

Topology errors use a stable object with error, message, fields, and conflicting_source_ids. Final approval additionally returns transaction_id, effective_at, retired source IDs, resulting version IDs, and lineage edge IDs.

Permissions Notes¶

• All listed APIs require authentication unless explicitly public.
• Non-staff visibility generally resolves to: own parcels + public parcels.
• Active dataset filters are applied at the queryset layer for parcel APIs.
• Dataset selector options are server-derived; client-side filtering is convenience only.
• Read APIs default to active rows (valid_to IS NULL, record_status = active) unless explicit historical query params are used.
• ref_ts historical reads apply validity-window filters and exclude void rows.

URL Semantics for Detail Routes¶

• /parcels/<uuid:pk>/ resolves a specific immutable version row.
• /parcels/id/<parcel_id>/ resolves the current active row for that parcel ID.