# 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"}}}}}}
```