> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapxagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> HTTP endpoints exposed by the MapX backend.

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:

```bash theme={null}
cd /data/xuxiang/mapx
pnpm docs:gen
```

Then sync the generated files:

```bash theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.