# Pins

Pin management

## GET /pins

> List all pins

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins":{"get":{"summary":"List all pins","tags":["Pins"],"parameters":[{"name":"zoneId","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of pins","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pin"}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"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":{"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a global pin (outside any zone)

> Creates a pin that is not associated with any specific zone. This allows pinning objects anywhere on the map without being restricted to defined zones.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins":{"post":{"summary":"Create a global pin (outside any zone)","description":"Creates a pin that is not associated with any specific zone. This allows pinning objects anywhere on the map without being restricted to defined zones.","tags":["Pins"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","contentUrl","contentType","geoPose"],"properties":{"title":{"type":"string","description":"Title of the pin"},"contentUrl":{"type":"string","format":"uri","description":"URL of the content associated with the pin"},"contentType":{"type":"string","enum":["IMAGE","VIDEO","GLB","USDZ","BIN","URL","APK","LENS","GCP","AUDIO"],"description":"Type of content associated with the pin"},"geoPose":{"$ref":"#/components/schemas/GeoPose","description":"Geographic position and orientation of the pin"},"latitude":{"type":"number","nullable":true,"description":"Latitude coordinate (optional, can be derived from geoPose)"},"longitude":{"type":"number","nullable":true,"description":"Longitude coordinate (optional, can be derived from geoPose)"}}}}}},"responses":{"201":{"description":"Global pin created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pin"}}}},"400":{"description":"Invalid pin data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"array","items":{"type":"object"}}}}}}},"500":{"description":"Failed to create pin","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"components":{"schemas":{"GeoPose":{"type":"object","required":["position","angles"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"angles":{"$ref":"#/components/schemas/YprAngles"}}},"Position":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number","description":"Latitude in decimal degrees"},"lon":{"type":"number","description":"Longitude in decimal degrees"},"h":{"type":"number","description":"Height/altitude in meters","default":0}}},"YprAngles":{"type":"object","required":["yaw","pitch","roll"],"properties":{"yaw":{"type":"number","description":"Yaw angle in degrees","default":0},"pitch":{"type":"number","description":"Pitch angle in degrees","default":0},"roll":{"type":"number","description":"Roll angle in degrees","default":0}}},"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"}}}}}}
```

## Delete a global pin

> Deletes a global pin by ID and removes any associated uploaded files. This operation cascades to clean up related file records.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins":{"delete":{"summary":"Delete a global pin","description":"Deletes a global pin by ID and removes any associated uploaded files. This operation cascades to clean up related file records.","tags":["Pins"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"The ID of the pin to delete"}],"responses":{"200":{"description":"Pin deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deletedPinId":{"type":"integer","description":"ID of the deleted pin"},"deletedFilesCount":{"type":"integer","description":"Number of associated uploaded files that were also deleted"}}}}}},"400":{"description":"Invalid pin ID or validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object"},"description":"Validation error details"}}}}}},"404":{"description":"Pin not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to delete pin","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Get a pin by ID

> Retrieves a single pin by ID with map associations. MVP: Public access, no authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins/{id}":{"get":{"summary":"Get a pin by ID","description":"Retrieves a single pin by ID with map associations. MVP: Public access, no authentication required.","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Pin ID"}],"responses":{"200":{"description":"Pin retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden - pin not accessible due to visibility settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"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"}}}}}}}
```

## PUT /pins/{id}

> Update a pin

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins/{id}":{"put":{"summary":"Update a pin","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","contentUrl","contentType"],"properties":{"title":{"type":"string"},"contentUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["IMAGE","VIDEO","GLB","USDZ","BIN","URL","APK","LENS","GCP","AUDIO","AR_WORLD"]},"gcpData":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Pin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"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"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## DELETE /pins/{id}

> Delete a pin

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/pins/{id}":{"delete":{"summary":"Delete a pin","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Pin deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"BadRequest":{"description":"Bad request","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"}}}}}}
```

## Record pin visit

> Marks a pin as visited for the authenticated user across all maps containing it. Returns updated progress for each map.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"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":{"/pins/{id}/visit":{"post":{"summary":"Record pin visit","description":"Marks a pin as visited for the authenticated user across all maps containing it. Returns updated progress for each map.","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Pin ID"}],"responses":{"200":{"description":"Pin visit recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"visitedMaps":{"type":"array","items":{"type":"integer"},"description":"Map IDs where the visit was recorded"},"progress":{"type":"array","items":{"type":"object","properties":{"mapId":{"type":"integer"},"totalPins":{"type":"integer"},"visitedPins":{"type":"integer"},"completionPercentage":{"type":"number"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update pin visibility

> Updates the visibility setting of a pin (public, private, or friends).

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"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":{"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":{"/pins/{id}/visibility":{"patch":{"summary":"Update pin visibility","description":"Updates the visibility setting of a pin (public, private, or friends).","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Pin ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["visibility"],"properties":{"visibility":{"type":"string","enum":["public","private","friends"]}}}}}},"responses":{"200":{"description":"Visibility updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update pin localization data

> Updates the AR relocalization data for a pin, including the reference photo URL, scan instructions, and camera pose hint.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"}],"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":{"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":{"/pins/{id}/localization":{"patch":{"summary":"Update pin localization data","description":"Updates the AR relocalization data for a pin, including the reference photo URL, scan instructions, and camera pose hint.","tags":["Pins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Pin ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relocalizationPhotoUrl":{"type":"string","format":"uri"},"scanInstructions":{"type":"string"},"cameraPoseHint":{"type":"object","properties":{"fov":{"type":"number"},"orientation":{"type":"string","enum":["portrait","landscape"]}},"additionalProperties":true}}}}}},"responses":{"200":{"description":"Localization data updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pin"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get blockchain status for a pin

> Retrieves the blockchain sync status, transaction signature, explorer URL, and transaction history for a specific pin. Authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Pins","description":"Pin management"},{"name":"Blockchain","description":"Blockchain synchronization operations for syncing entities to Solana blockchain"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"DynamicAuth":[]}],"components":{"securitySchemes":{"DynamicAuth":{"type":"apiKey","in":"header","name":"X-Dynamic-User-Id","description":"Dynamic authentication header. Required for blockchain endpoints and other authenticated operations."}},"schemas":{"PinBlockchainStatus":{"type":"object","properties":{"id":{"type":"integer","description":"Pin ID"},"blockchainSignature":{"type":"string","nullable":true,"description":"Blockchain transaction signature"},"blockchainTxUrl":{"type":"string","nullable":true,"format":"uri","description":"URL to view transaction on Solana Explorer"},"blockchainSyncedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the pin was synced to blockchain"}}},"BlockchainTransaction":{"type":"object","properties":{"id":{"type":"integer","description":"Transaction record ID"},"entityType":{"type":"string","enum":["Zone","Pin","Gcp","File"],"description":"Type of entity"},"entityId":{"type":"integer","description":"ID of the entity"},"signature":{"type":"string","description":"Transaction signature"},"network":{"type":"string","enum":["devnet","mainnet","testnet"],"description":"Solana network"},"status":{"type":"string","enum":["pending","confirmed","failed"],"description":"Transaction status"},"blockHeight":{"type":"integer","nullable":true,"description":"Block height at which transaction was confirmed"},"createdAt":{"type":"string","format":"date-time","description":"When the transaction was created"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/pins/{id}/blockchain":{"get":{"summary":"Get blockchain status for a pin","description":"Retrieves the blockchain sync status, transaction signature, explorer URL, and transaction history for a specific pin. Authentication required.","tags":["Pins","Blockchain"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Pin ID"}],"responses":{"200":{"description":"Blockchain status retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["pin","transactions"],"properties":{"pin":{"$ref":"#/components/schemas/PinBlockchainStatus"},"transactions":{"type":"array","description":"Transaction history (last 10 transactions)","items":{"$ref":"#/components/schemas/BlockchainTransaction"}}}}}}},"400":{"description":"Invalid pin ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Pin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Failed to fetch blockchain status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```