API reference

The interactive API reference is generated from the OpenAPI contract and available under the API Reference group in the sidebar. The contract is served by the API itself at GET /api/v1/openapi.json and stored in openapi.json at the root of this repository. The API resource is named session for historical reasons; it represents a persistent project in the product (a workspace with map state, layers, files, chat history, and reports). The full endpoint list is generated from the source repository and stored in source/api-routes.json. If this page looks stale, regenerate the source pack:

cd /data/xuxiang/mapx
pnpm docs:gen

Then sync the generated files:

cp -r /data/xuxiang/mapx/docs-source/* source/
cp /data/xuxiang/mapx/docs-source/openapi.json openapi.json

Public API endpoints

Method	Path	Purpose
`GET`	`/api/v1/sessions`	List projects
`POST`	`/api/v1/sessions`	Create a project
`GET`	`/api/v1/sessions/{id}`	Get a project
`PATCH`	`/api/v1/sessions/{id}`	Partially update a project
`DELETE`	`/api/v1/sessions/{id}`	Delete a project
`GET`	`/api/v1/sessions/{id}/map`	Get the project map state
`POST`	`/api/v1/sessions/{id}/chat`	Start an AI chat turn
`POST`	`/api/v1/sessions/{id}/ask/respond`	Answer a pending AI question
`GET`	`/api/v1/sessions/{id}/files`	List project files
`POST`	`/api/v1/sessions/{id}/files`	Upload a file
`GET`	`/api/v1/sessions/{id}/files/{fileId}/content`	Get file content
`DELETE`	`/api/v1/sessions/{id}/files/{fileId}`	Delete a file
`GET`	`/api/v1/sessions/{id}/assets`	List all data assets
`GET`	`/api/v1/sessions/{id}/layers`	List project layers
`GET`	`/api/v1/sessions/{id}/layers/{layerId}`	Get layer details
`PATCH`	`/api/v1/sessions/{id}/layers/{layerId}`	Rename a layer or change its visibility
`DELETE`	`/api/v1/sessions/{id}/layers/{layerId}`	Delete a layer
`PUT`	`/api/v1/sessions/{id}/layers/order`	Reorder all layers in one request
`PUT`	`/api/v1/sessions/{id}/layers/{layerId}/style`	Update a layer style
`POST`	`/api/v1/sessions/{id}/map/actions`	Dispatch map actions
`POST`	`/api/v1/sessions/{id}/reports`	Save an HTML report
`GET`	`/api/v1/sessions/{id}/reports/{fileId}`	Get report metadata
`POST`	`/api/v1/sessions/{id}/live-view-url`	Get the live view URL for a project
`POST`	`/api/v1/sessions/{id}/static-view-url`	Get the static embed URL for a project
`GET`	`/api/v1/api-keys`	List API keys
`POST`	`/api/v1/api-keys`	Create an API key
`DELETE`	`/api/v1/api-keys/{keyId}`	Revoke an API key
`GET`	`/api/v1/verify`	Verify the API key
`GET`	`/api/v1/usage`	Get current plan usage

For request/response schemas, use the interactive API Reference group in the sidebar, generated from the OpenAPI contract. Platform-internal endpoints under /api/internal/* are not part of the public API and are intentionally not listed here.

Supported upload types

POST /api/v1/sessions/{id}/files accepts the following file types (max 50MB per file, configurable via UPLOAD_MAX_SIZE_MB):

Extension	Handling
`.geojson` / `.json`	Added directly as a map layer
`.csv` / `.xlsx` / `.xls`	Converted to a GeoJSON layer
`.tif` / `.tiff`	Converted to a COG image layer
`.txt` / `.md` / `.docx` / `.doc` / `.pdf`	Stored as a plain file (no layer)

Capability scopes

API keys grant access through capability scopes. ["*"] (or an empty scopes array) grants all access; otherwise only the listed scopes are allowed.

Scope	Required by
`session`	Project list/create/get/update/delete, usage
`chat`	Chat turns, ask/respond
`files`	File list, upload, delete, file content
`layers`	Layer list, details, updates, style, reorder
`map`	Map actions
`reports`	Report save, report metadata
`remote`	Live/static view URLs
`keys`	API key management

Map actions

POST /api/v1/sessions/{id}/map/actions accepts an array of action objects. Each action requires a type; the parameters depend on the type. Legacy map.* prefixed aliases (for example map.flyTo) are also accepted. add_tile_layer sent without a layer_id is persisted by the backend (deduplicated by URL) and the created layer id is returned in the response.

View & camera

Type	Required	Optional	Description
`fly_to`	`center`	`zoom`, `bearing`, `pitch`	Fly to a map center
`jump_to`	`center`	`zoom`	Jump to a center without animation
`fit_bounds`	`bbox`	`padding`	Fit the viewport to a bounding box
`go_home`	—	—	Reset to the default world view
`zoom_in` / `zoom_out`	—	—	Zoom one level
`pan`	`direction`	`amount`	Pan in a direction
`zoom_to_layer`	`layer_id`	—	Zoom to a layer’s extent

Layers

Type	Required	Optional	Description
`add_geojson_layer`	`layer_id`, one of `geojson` / `file_id`	`session_id`, `file_path`, `layer_type`, `name`, `columns`, `style`	Add a GeoJSON layer from inline data or a server file
`add_tile_layer`	`url`, `layer_id`	`layer_name`, `attribution`, `opacity`, `min_zoom`, `max_zoom`, `tile_size`	Add a raster tile layer
`add_cog_layer`	`url`, `layer_id`	`layer_name`, `opacity`, `min_zoom`, `max_zoom`	Add a Cloud-Optimized GeoTIFF layer
`remove_layer`	`layer_id`	—	Remove a layer and its source
`rename_layer`	`layer_id`, `name`	—	Rename a layer
`set_layer_visibility`	`layer_id`, `visible`	—	Show or hide a layer
`move_layer_up` / `move_layer_down`	`layer_id`	—	Reorder a layer
`update_layer_style`	`layer_id`, `style`	—	Replace a layer’s style

Basemap & masks

Type	Required	Optional	Description
`set_basemap_style`	`style`	—	Switch the basemap style
`set_basemap_category`	`category_key`	`color`, `visible`	Override a basemap category
`set_country_mask`	`country_code`	`visible`, `color`	Show or hide a country mask
`set_custom_mask`	—	`geojson`, `color`	Set or clear a custom polygon mask

System & notifications

Type	Required	Optional	Description
`file_generated`	`file_id`, `file_name`	`description`, `url`	Notify the UI that a file/report was generated (backend-emitted)
`clear_layers`	—	—	Remove all AI-created layers

Get Started

API Reference

Client

API reference

Public API endpoints

Supported upload types

Capability scopes

Map actions

View & camera

Layers

Basemap & masks

System & notifications

​Public API endpoints

​Supported upload types

​Capability scopes

​Map actions

​View & camera

​Layers

​Basemap & masks

​System & notifications

Public API endpoints

Supported upload types

Capability scopes

Map actions

View & camera

Layers

Basemap & masks

System & notifications