# Maps

Map management, pin ordering, sharing, and visit tracking

## List all maps

> Fetches all maps accessible to the authenticated user, including their pins, visit counts, and GCP details.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"Map":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"coverImage":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"userId":{"type":"string"},"pins":{"type":"array","items":{"type":"object","properties":{"pin":{"$ref":"#/components/schemas/Pin"},"order":{"type":"integer"}}}},"_count":{"type":"object","properties":{"visits":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}}},"Pin":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"geoPose":{"type":"object","description":"JSON object containing geographic position and orientation data"},"contentType":{"type":"string","enum":["APK","GLB","IMAGE","VIDEO","URL","LENS","GCP","AUDIO","USDZ","BIN"]},"contentUrl":{"type":"string"},"localizationData":{"type":"object","nullable":true,"description":"ARWorld localization data for iOS AR experiences","properties":{"trackingMode":{"type":"string","enum":["WORLD","GEO"],"description":"AR tracking mode for the pin"},"worldmapURL":{"type":"string","format":"uri","nullable":true,"description":"S3 URL of the ARWorld binary data"}}},"zoneId":{"type":"integer","nullable":true},"gcpId":{"type":"integer","nullable":true},"userId":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private","friends"],"description":"Pin visibility setting"},"relocalizationPhotoUrl":{"type":"string","nullable":true,"description":"URL of the relocalization reference photo"},"scanInstructions":{"type":"string","nullable":true,"description":"Instructions for scanning/relocalizing"},"cameraPoseHint":{"type":"object","nullable":true,"description":"Camera pose hint for AR relocalization"},"blockchainSignature":{"type":"string","nullable":true},"blockchainTxUrl":{"type":"string","nullable":true},"blockchainSyncedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps":{"get":{"summary":"List all maps","description":"Fetches all maps accessible to the authenticated user, including their pins, visit counts, and GCP details.","tags":["Maps"],"parameters":[{"name":"isPublic","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter for public maps only"},{"name":"friends","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter for friends' public maps"}],"responses":{"200":{"description":"List of maps","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Map"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## POST /maps

> Create a new map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"Map":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"coverImage":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"userId":{"type":"string"},"pins":{"type":"array","items":{"type":"object","properties":{"pin":{"$ref":"#/components/schemas/Pin"},"order":{"type":"integer"}}}},"_count":{"type":"object","properties":{"visits":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}}},"Pin":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"geoPose":{"type":"object","description":"JSON object containing geographic position and orientation data"},"contentType":{"type":"string","enum":["APK","GLB","IMAGE","VIDEO","URL","LENS","GCP","AUDIO","USDZ","BIN"]},"contentUrl":{"type":"string"},"localizationData":{"type":"object","nullable":true,"description":"ARWorld localization data for iOS AR experiences","properties":{"trackingMode":{"type":"string","enum":["WORLD","GEO"],"description":"AR tracking mode for the pin"},"worldmapURL":{"type":"string","format":"uri","nullable":true,"description":"S3 URL of the ARWorld binary data"}}},"zoneId":{"type":"integer","nullable":true},"gcpId":{"type":"integer","nullable":true},"userId":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private","friends"],"description":"Pin visibility setting"},"relocalizationPhotoUrl":{"type":"string","nullable":true,"description":"URL of the relocalization reference photo"},"scanInstructions":{"type":"string","nullable":true,"description":"Instructions for scanning/relocalizing"},"cameraPoseHint":{"type":"object","nullable":true,"description":"Camera pose hint for AR relocalization"},"blockchainSignature":{"type":"string","nullable":true},"blockchainTxUrl":{"type":"string","nullable":true},"blockchainSyncedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps":{"post":{"summary":"Create a new map","tags":["Maps"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1},"description":{"type":"string"},"isPublic":{"type":"boolean","default":false},"coverImage":{"type":"string","format":"uri"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}}}}}},"responses":{"201":{"description":"Map created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Map"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /maps/{id}

> Get a map by ID

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"Map":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"coverImage":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"userId":{"type":"string"},"pins":{"type":"array","items":{"type":"object","properties":{"pin":{"$ref":"#/components/schemas/Pin"},"order":{"type":"integer"}}}},"_count":{"type":"object","properties":{"visits":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}}},"Pin":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"geoPose":{"type":"object","description":"JSON object containing geographic position and orientation data"},"contentType":{"type":"string","enum":["APK","GLB","IMAGE","VIDEO","URL","LENS","GCP","AUDIO","USDZ","BIN"]},"contentUrl":{"type":"string"},"localizationData":{"type":"object","nullable":true,"description":"ARWorld localization data for iOS AR experiences","properties":{"trackingMode":{"type":"string","enum":["WORLD","GEO"],"description":"AR tracking mode for the pin"},"worldmapURL":{"type":"string","format":"uri","nullable":true,"description":"S3 URL of the ARWorld binary data"}}},"zoneId":{"type":"integer","nullable":true},"gcpId":{"type":"integer","nullable":true},"userId":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private","friends"],"description":"Pin visibility setting"},"relocalizationPhotoUrl":{"type":"string","nullable":true,"description":"URL of the relocalization reference photo"},"scanInstructions":{"type":"string","nullable":true,"description":"Instructions for scanning/relocalizing"},"cameraPoseHint":{"type":"object","nullable":true,"description":"Camera pose hint for AR relocalization"},"blockchainSignature":{"type":"string","nullable":true},"blockchainTxUrl":{"type":"string","nullable":true},"blockchainSyncedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}":{"get":{"summary":"Get a map by ID","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Map ID"}],"responses":{"200":{"description":"Map details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Map"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## DELETE /maps/{id}

> Delete a map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/maps/{id}":{"delete":{"summary":"Delete a map","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Map deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deletedPins":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## PATCH /maps/{id}

> Update a map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"Map":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"coverImage":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"userId":{"type":"string"},"pins":{"type":"array","items":{"type":"object","properties":{"pin":{"$ref":"#/components/schemas/Pin"},"order":{"type":"integer"}}}},"_count":{"type":"object","properties":{"visits":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}}},"Pin":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"geoPose":{"type":"object","description":"JSON object containing geographic position and orientation data"},"contentType":{"type":"string","enum":["APK","GLB","IMAGE","VIDEO","URL","LENS","GCP","AUDIO","USDZ","BIN"]},"contentUrl":{"type":"string"},"localizationData":{"type":"object","nullable":true,"description":"ARWorld localization data for iOS AR experiences","properties":{"trackingMode":{"type":"string","enum":["WORLD","GEO"],"description":"AR tracking mode for the pin"},"worldmapURL":{"type":"string","format":"uri","nullable":true,"description":"S3 URL of the ARWorld binary data"}}},"zoneId":{"type":"integer","nullable":true},"gcpId":{"type":"integer","nullable":true},"userId":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private","friends"],"description":"Pin visibility setting"},"relocalizationPhotoUrl":{"type":"string","nullable":true,"description":"URL of the relocalization reference photo"},"scanInstructions":{"type":"string","nullable":true,"description":"Instructions for scanning/relocalizing"},"cameraPoseHint":{"type":"object","nullable":true,"description":"Camera pose hint for AR relocalization"},"blockchainSignature":{"type":"string","nullable":true},"blockchainTxUrl":{"type":"string","nullable":true},"blockchainSyncedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}":{"patch":{"summary":"Update a map","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"coverImage":{"type":"string","format":"uri","nullable":true},"latitude":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"longitude":{"type":"number","minimum":-180,"maximum":180,"nullable":true}}}}}},"responses":{"200":{"description":"Map updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Map"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get map completion progress

> Gets the authenticated user's completion progress for a map, including which pins have been visited.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"MapProgress":{"type":"object","properties":{"mapId":{"type":"integer"},"mapTitle":{"type":"string"},"totalPins":{"type":"integer"},"visitedPins":{"type":"integer"},"completionPercentage":{"type":"number"},"visitedPinIds":{"type":"array","items":{"type":"integer"}},"pins":{"type":"array","items":{"type":"object","properties":{"pinId":{"type":"integer"},"order":{"type":"integer"},"title":{"type":"string"},"visited":{"type":"boolean"},"visitedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}/progress":{"get":{"summary":"Get map completion progress","description":"Gets the authenticated user's completion progress for a map, including which pins have been visited.","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Map ID"}],"responses":{"200":{"description":"Map progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapProgress"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Reset map visit progress

> Resets all visit records for a map. WARNING: This affects all users' progress for this map.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/maps/{id}/reset":{"post":{"summary":"Reset map visit progress","description":"Resets all visit records for a map. WARNING: This affects all users' progress for this map.","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Progress reset successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deletedVisits":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## POST /maps/{id}/pins

> Add pin to map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"MapPin":{"type":"object","properties":{"mapId":{"type":"integer"},"pinId":{"type":"integer"},"order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}/pins":{"post":{"summary":"Add pin to map","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pinId"],"properties":{"pinId":{"type":"integer","minimum":1},"order":{"type":"integer","minimum":0,"default":0}}}}}},"responses":{"201":{"description":"Pin added to map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapPin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## DELETE /maps/{id}/pins

> Remove pin from map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/maps/{id}/pins":{"delete":{"summary":"Remove pin from map","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"pinId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Pin removed from map","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## PATCH /maps/{id}/pins

> Update pin order in map

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"MapPin":{"type":"object","properties":{"mapId":{"type":"integer"},"pinId":{"type":"integer"},"order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}/pins":{"patch":{"summary":"Update pin order in map","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pinId","order"],"properties":{"pinId":{"type":"integer","minimum":1},"order":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Pin order updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapPin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /maps/{id}/share

> Get users a map is shared with

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"MapShare":{"type":"object","properties":{"id":{"type":"integer"},"mapId":{"type":"integer"},"userId":{"type":"string"},"canEdit":{"type":"boolean"},"sharedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}/share":{"get":{"summary":"Get users a map is shared with","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"List of share records","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MapShare"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## POST /maps/{id}/share

> Share map with a user

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"schemas":{"MapShare":{"type":"object","properties":{"id":{"type":"integer"},"mapId":{"type":"integer"},"userId":{"type":"string"},"canEdit":{"type":"boolean"},"sharedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/maps/{id}/share":{"post":{"summary":"Share map with a user","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","minLength":1},"canEdit":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Map shared successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapShare"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## DELETE /maps/{id}/share

> Unshare map with a user

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Maps","description":"Map management, pin ordering, sharing, and visit tracking"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/maps/{id}/share":{"delete":{"summary":"Unshare map with a user","tags":["Maps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"userId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Map unshared","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meshmap.com/api/zones/maps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.