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


---

# 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/pins.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.