Pins

Pin management

List all pins

get

Query parameters

zoneIdintegerOptional

Responses

200

List of pins

application/json

idintegerOptional

titlestringOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

geoPoseobjectOptional

JSON object containing geographic position and orientation data

contentTypestring · enumOptionalPossible values:

contentUrlstringOptional

zoneIdinteger · nullableOptional

gcpIdinteger · nullableOptional

userIdstring · nullableOptional

visibilitystring · enumOptional

Pin visibility setting

Possible values:

relocalizationPhotoUrlstring · nullableOptional

URL of the relocalization reference photo

scanInstructionsstring · nullableOptional

Instructions for scanning/relocalizing

cameraPoseHintobject · nullableOptional

Camera pose hint for AR relocalization

blockchainSignaturestring · nullableOptional

blockchainTxUrlstring · nullableOptional

blockchainSyncedAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

500

Internal server error

application/json

get

/pins

HTTPcURLJavaScriptPython

GET /api/pins HTTP/1.1
Accept: */*

[
  {
    "id": 1,
    "title": "text",
    "latitude": 1,
    "longitude": 1,
    "geoPose": {},
    "contentType": "APK",
    "contentUrl": "text",
    "localizationData": {
      "trackingMode": "WORLD",
      "worldmapURL": "https://example.com"
    },
    "zoneId": 1,
    "gcpId": 1,
    "userId": "text",
    "visibility": "public",
    "relocalizationPhotoUrl": "text",
    "scanInstructions": "text",
    "cameraPoseHint": {},
    "blockchainSignature": "text",
    "blockchainTxUrl": "text",
    "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
    "createdAt": "2026-02-27T21:43:14.097Z",
    "updatedAt": "2026-02-27T21:43:14.097Z"
  }
]

Create a global pin (outside any zone)

post

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.

Body

application/json

titlestringRequired

Title of the pin

contentUrlstring · uriRequired

URL of the content associated with the pin

contentTypestring · enumRequired

Type of content associated with the pin

Possible values:

latitudenumber · nullableOptional

Latitude coordinate (optional, can be derived from geoPose)

longitudenumber · nullableOptional

Longitude coordinate (optional, can be derived from geoPose)

Responses

201

Global pin created successfully

application/json

400

Invalid pin data

application/json

500

Failed to create pin

application/json

post

/pins

HTTPcURLJavaScriptPython

POST /api/pins HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 185

{
  "title": "text",
  "contentUrl": "https://example.com",
  "contentType": "IMAGE",
  "geoPose": {
    "position": {
      "lat": 1,
      "lon": 1,
      "h": 0
    },
    "angles": {
      "yaw": 0,
      "pitch": 0,
      "roll": 0
    }
  },
  "latitude": 1,
  "longitude": 1
}

{
  "id": 1,
  "title": "text",
  "latitude": 1,
  "longitude": 1,
  "geoPose": {},
  "contentType": "APK",
  "contentUrl": "text",
  "localizationData": {
    "trackingMode": "WORLD",
    "worldmapURL": "https://example.com"
  },
  "zoneId": 1,
  "gcpId": 1,
  "userId": "text",
  "visibility": "public",
  "relocalizationPhotoUrl": "text",
  "scanInstructions": "text",
  "cameraPoseHint": {},
  "blockchainSignature": "text",
  "blockchainTxUrl": "text",
  "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
  "createdAt": "2026-02-27T21:43:14.097Z",
  "updatedAt": "2026-02-27T21:43:14.097Z"
}

Delete a global pin

delete

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

Query parameters

idstringRequired

The ID of the pin to delete

Responses

200

Pin deleted successfully

application/json

messagestringOptionalExample: Pin deleted successfully

deletedPinIdintegerOptional

ID of the deleted pin

deletedFilesCountintegerOptional

Number of associated uploaded files that were also deleted

400

Invalid pin ID or validation failed

application/json

404

Pin not found

application/json

500

Failed to delete pin

application/json

delete

/pins

HTTPcURLJavaScriptPython

DELETE /api/pins?id=text HTTP/1.1
Accept: */*

{
  "message": "Pin deleted successfully",
  "deletedPinId": 1,
  "deletedFilesCount": 1
}

Get a pin by ID

get

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

Path parameters

idintegerRequired

Pin ID

Responses

200

Pin retrieved successfully

application/json

idintegerOptional

titlestringOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

geoPoseobjectOptional

JSON object containing geographic position and orientation data

contentTypestring · enumOptionalPossible values:

contentUrlstringOptional

zoneIdinteger · nullableOptional

gcpIdinteger · nullableOptional

userIdstring · nullableOptional

visibilitystring · enumOptional

Pin visibility setting

Possible values:

relocalizationPhotoUrlstring · nullableOptional

URL of the relocalization reference photo

scanInstructionsstring · nullableOptional

Instructions for scanning/relocalizing

cameraPoseHintobject · nullableOptional

Camera pose hint for AR relocalization

blockchainSignaturestring · nullableOptional

blockchainTxUrlstring · nullableOptional

blockchainSyncedAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden - pin not accessible due to visibility settings

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/pins/{id}

HTTPcURLJavaScriptPython

GET /api/pins/{id} HTTP/1.1
Accept: */*

{
  "id": 1,
  "title": "text",
  "latitude": 1,
  "longitude": 1,
  "geoPose": {},
  "contentType": "APK",
  "contentUrl": "text",
  "localizationData": {
    "trackingMode": "WORLD",
    "worldmapURL": "https://example.com"
  },
  "zoneId": 1,
  "gcpId": 1,
  "userId": "text",
  "visibility": "public",
  "relocalizationPhotoUrl": "text",
  "scanInstructions": "text",
  "cameraPoseHint": {},
  "blockchainSignature": "text",
  "blockchainTxUrl": "text",
  "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
  "createdAt": "2026-02-27T21:43:14.097Z",
  "updatedAt": "2026-02-27T21:43:14.097Z"
}

Update a pin

put

Path parameters

idintegerRequired

Body

application/json

titlestringRequired

contentUrlstring · uriRequired

contentTypestring · enumRequiredPossible values:

gcpDatastring · nullableOptional

Responses

200

Pin updated

application/json

idintegerOptional

titlestringOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

geoPoseobjectOptional

JSON object containing geographic position and orientation data

contentTypestring · enumOptionalPossible values:

contentUrlstringOptional

zoneIdinteger · nullableOptional

gcpIdinteger · nullableOptional

userIdstring · nullableOptional

visibilitystring · enumOptional

Pin visibility setting

Possible values:

relocalizationPhotoUrlstring · nullableOptional

URL of the relocalization reference photo

scanInstructionsstring · nullableOptional

Instructions for scanning/relocalizing

cameraPoseHintobject · nullableOptional

Camera pose hint for AR relocalization

blockchainSignaturestring · nullableOptional

blockchainTxUrlstring · nullableOptional

blockchainSyncedAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Bad request

application/json

500

Internal server error

application/json

put

/pins/{id}

HTTPcURLJavaScriptPython

PUT /api/pins/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "title": "text",
  "contentUrl": "https://example.com",
  "contentType": "IMAGE",
  "gcpData": "text"
}

{
  "id": 1,
  "title": "text",
  "latitude": 1,
  "longitude": 1,
  "geoPose": {},
  "contentType": "APK",
  "contentUrl": "text",
  "localizationData": {
    "trackingMode": "WORLD",
    "worldmapURL": "https://example.com"
  },
  "zoneId": 1,
  "gcpId": 1,
  "userId": "text",
  "visibility": "public",
  "relocalizationPhotoUrl": "text",
  "scanInstructions": "text",
  "cameraPoseHint": {},
  "blockchainSignature": "text",
  "blockchainTxUrl": "text",
  "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
  "createdAt": "2026-02-27T21:43:14.097Z",
  "updatedAt": "2026-02-27T21:43:14.097Z"
}

Delete a pin

delete

Path parameters

idintegerRequired

Responses

204

Pin deleted

400

Bad request

application/json

404

Resource not found

application/json

500

Internal server error

application/json

delete

/pins/{id}

HTTPcURLJavaScriptPython

DELETE /api/pins/{id} HTTP/1.1
Accept: */*

No content

Record pin visit

post

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

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer token authentication. Pass the session token obtained from /auth/sync.

Path parameters

idintegerRequired

Pin ID

Responses

200

Pin visit recorded

application/json

successbooleanOptional

visitedMapsinteger[]Optional

Map IDs where the visit was recorded

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

post

/pins/{id}/visit

HTTPcURLJavaScriptPython

POST /api/pins/{id}/visit HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "visitedMaps": [
    1
  ],
  "progress": [
    {
      "mapId": 1,
      "totalPins": 1,
      "visitedPins": 1,
      "completionPercentage": 1
    }
  ]
}

Update pin visibility

patch

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

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer token authentication. Pass the session token obtained from /auth/sync.

Path parameters

idintegerRequired

Pin ID

Body

application/json

visibilitystring · enumRequiredPossible values:

Responses

200

Visibility updated

application/json

idintegerOptional

titlestringOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

geoPoseobjectOptional

JSON object containing geographic position and orientation data

contentTypestring · enumOptionalPossible values:

contentUrlstringOptional

zoneIdinteger · nullableOptional

gcpIdinteger · nullableOptional

userIdstring · nullableOptional

visibilitystring · enumOptional

Pin visibility setting

Possible values:

relocalizationPhotoUrlstring · nullableOptional

URL of the relocalization reference photo

scanInstructionsstring · nullableOptional

Instructions for scanning/relocalizing

cameraPoseHintobject · nullableOptional

Camera pose hint for AR relocalization

blockchainSignaturestring · nullableOptional

blockchainTxUrlstring · nullableOptional

blockchainSyncedAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

patch

/pins/{id}/visibility

HTTPcURLJavaScriptPython

PATCH /api/pins/{id}/visibility HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "visibility": "public"
}

{
  "id": 1,
  "title": "text",
  "latitude": 1,
  "longitude": 1,
  "geoPose": {},
  "contentType": "APK",
  "contentUrl": "text",
  "localizationData": {
    "trackingMode": "WORLD",
    "worldmapURL": "https://example.com"
  },
  "zoneId": 1,
  "gcpId": 1,
  "userId": "text",
  "visibility": "public",
  "relocalizationPhotoUrl": "text",
  "scanInstructions": "text",
  "cameraPoseHint": {},
  "blockchainSignature": "text",
  "blockchainTxUrl": "text",
  "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
  "createdAt": "2026-02-27T21:43:14.097Z",
  "updatedAt": "2026-02-27T21:43:14.097Z"
}

Update pin localization data

patch

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

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer token authentication. Pass the session token obtained from /auth/sync.

Path parameters

idintegerRequired

Pin ID

Body

application/json

relocalizationPhotoUrlstring · uriOptional

scanInstructionsstringOptional

Responses

200

Localization data updated

application/json

idintegerOptional

titlestringOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

geoPoseobjectOptional

JSON object containing geographic position and orientation data

contentTypestring · enumOptionalPossible values:

contentUrlstringOptional

zoneIdinteger · nullableOptional

gcpIdinteger · nullableOptional

userIdstring · nullableOptional

visibilitystring · enumOptional

Pin visibility setting

Possible values:

relocalizationPhotoUrlstring · nullableOptional

URL of the relocalization reference photo

scanInstructionsstring · nullableOptional

Instructions for scanning/relocalizing

cameraPoseHintobject · nullableOptional

Camera pose hint for AR relocalization

blockchainSignaturestring · nullableOptional

blockchainTxUrlstring · nullableOptional

blockchainSyncedAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

patch

/pins/{id}/localization

HTTPcURLJavaScriptPython

PATCH /api/pins/{id}/localization HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "relocalizationPhotoUrl": "https://example.com",
  "scanInstructions": "text",
  "cameraPoseHint": {
    "fov": 1,
    "orientation": "portrait",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": 1,
  "title": "text",
  "latitude": 1,
  "longitude": 1,
  "geoPose": {},
  "contentType": "APK",
  "contentUrl": "text",
  "localizationData": {
    "trackingMode": "WORLD",
    "worldmapURL": "https://example.com"
  },
  "zoneId": 1,
  "gcpId": 1,
  "userId": "text",
  "visibility": "public",
  "relocalizationPhotoUrl": "text",
  "scanInstructions": "text",
  "cameraPoseHint": {},
  "blockchainSignature": "text",
  "blockchainTxUrl": "text",
  "blockchainSyncedAt": "2026-02-27T21:43:14.097Z",
  "createdAt": "2026-02-27T21:43:14.097Z",
  "updatedAt": "2026-02-27T21:43:14.097Z"
}

Get blockchain status for a pin

get

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

Authorizations

DynamicAuth

X-Dynamic-User-IdstringRequired

Dynamic authentication header. Required for blockchain endpoints and other authenticated operations.

Path parameters

idintegerRequired

Pin ID

Responses

200

Blockchain status retrieved successfully

application/json

400

Invalid pin ID

application/json

401

Unauthorized

application/json

404

Pin not found

application/json

500

Failed to fetch blockchain status

application/json

get

/pins/{id}/blockchain

HTTPcURLJavaScriptPython

GET /api/pins/{id}/blockchain HTTP/1.1
X-Dynamic-User-Id: YOUR_API_KEY
Accept: */*

{
  "pin": {
    "id": 1,
    "blockchainSignature": "text",
    "blockchainTxUrl": "https://example.com",
    "blockchainSyncedAt": "2026-02-27T21:43:14.097Z"
  },
  "transactions": [
    {
      "id": 1,
      "entityType": "Zone",
      "entityId": 1,
      "signature": "text",
      "network": "devnet",
      "status": "pending",
      "blockHeight": 1,
      "createdAt": "2026-02-27T21:43:14.097Z"
    }
  ]
}