Maps

Map management, pin ordering, sharing, and visit tracking

List all maps

get

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

Authorizations

BearerAuth

AuthorizationstringRequired

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

Query parameters

isPublicstring · enumOptional

Filter for public maps only

Possible values:

friendsstring · enumOptional

Filter for friends' public maps

Possible values:

Responses

200

List of maps

application/json

idintegerOptional

titlestringOptional

descriptionstring · nullableOptional

isPublicbooleanOptional

coverImagestring · nullableOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

userIdstringOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

deletedAtstring · date-time · nullableOptional

401

Unauthorized

application/json

500

Internal server error

application/json

get

/maps

HTTPcURLJavaScriptPython

GET /api/maps HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": 1,
    "title": "text",
    "description": "text",
    "isPublic": true,
    "coverImage": "text",
    "latitude": 1,
    "longitude": 1,
    "userId": "text",
    "pins": [
      {
        "pin": {
          "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-27T22:03:25.191Z",
          "createdAt": "2026-02-27T22:03:25.191Z",
          "updatedAt": "2026-02-27T22:03:25.191Z"
        },
        "order": 1
      }
    ],
    "_count": {
      "visits": 1
    },
    "createdAt": "2026-02-27T22:03:25.191Z",
    "updatedAt": "2026-02-27T22:03:25.191Z",
    "deletedAt": "2026-02-27T22:03:25.191Z"
  }
]

Create a new map

post

Authorizations

BearerAuth

AuthorizationstringRequired

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

Body

application/json

titlestring · min: 1Required

descriptionstringOptional

isPublicbooleanOptionalDefault: false

coverImagestring · uriOptional

latitudenumber · min: -90 · max: 90Optional

longitudenumber · min: -180 · max: 180Optional

Responses

201

Map created

application/json

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/maps

HTTPcURLJavaScriptPython

POST /api/maps HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "title": "text",
  "description": "text",
  "isPublic": false,
  "coverImage": "https://example.com",
  "latitude": 1,
  "longitude": 1
}

{
  "id": 1,
  "title": "text",
  "description": "text",
  "isPublic": true,
  "coverImage": "text",
  "latitude": 1,
  "longitude": 1,
  "userId": "text",
  "pins": [
    {
      "pin": {
        "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-27T22:03:25.191Z",
        "createdAt": "2026-02-27T22:03:25.191Z",
        "updatedAt": "2026-02-27T22:03:25.191Z"
      },
      "order": 1
    }
  ],
  "_count": {
    "visits": 1
  },
  "createdAt": "2026-02-27T22:03:25.191Z",
  "updatedAt": "2026-02-27T22:03:25.191Z",
  "deletedAt": "2026-02-27T22:03:25.191Z"
}

Get a map by ID

get

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Map ID

Responses

200

Map details

application/json

idintegerOptional

titlestringOptional

descriptionstring · nullableOptional

isPublicbooleanOptional

coverImagestring · nullableOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

userIdstringOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

deletedAtstring · date-time · nullableOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/maps/{id}

HTTPcURLJavaScriptPython

GET /api/maps/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "title": "text",
  "description": "text",
  "isPublic": true,
  "coverImage": "text",
  "latitude": 1,
  "longitude": 1,
  "userId": "text",
  "pins": [
    {
      "pin": {
        "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-27T22:03:25.191Z",
        "createdAt": "2026-02-27T22:03:25.191Z",
        "updatedAt": "2026-02-27T22:03:25.191Z"
      },
      "order": 1
    }
  ],
  "_count": {
    "visits": 1
  },
  "createdAt": "2026-02-27T22:03:25.191Z",
  "updatedAt": "2026-02-27T22:03:25.191Z",
  "deletedAt": "2026-02-27T22:03:25.191Z"
}

Delete a map

delete

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Responses

200

Map deleted

application/json

messagestringOptional

deletedPinsintegerOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

delete

/maps/{id}

HTTPcURLJavaScriptPython

DELETE /api/maps/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "deletedPins": 1
}

Update a map

patch

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Body

application/json

titlestring · min: 1Optional

descriptionstring · nullableOptional

isPublicbooleanOptional

coverImagestring · uri · nullableOptional

latitudenumber · min: -90 · max: 90 · nullableOptional

longitudenumber · min: -180 · max: 180 · nullableOptional

Responses

200

Map updated

application/json

idintegerOptional

titlestringOptional

descriptionstring · nullableOptional

isPublicbooleanOptional

coverImagestring · nullableOptional

latitudenumber · nullableOptional

longitudenumber · nullableOptional

userIdstringOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

deletedAtstring · date-time · nullableOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

patch

/maps/{id}

HTTPcURLJavaScriptPython

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

{
  "title": "text",
  "description": "text",
  "isPublic": true,
  "coverImage": "https://example.com",
  "latitude": 1,
  "longitude": 1
}

{
  "id": 1,
  "title": "text",
  "description": "text",
  "isPublic": true,
  "coverImage": "text",
  "latitude": 1,
  "longitude": 1,
  "userId": "text",
  "pins": [
    {
      "pin": {
        "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-27T22:03:25.191Z",
        "createdAt": "2026-02-27T22:03:25.191Z",
        "updatedAt": "2026-02-27T22:03:25.191Z"
      },
      "order": 1
    }
  ],
  "_count": {
    "visits": 1
  },
  "createdAt": "2026-02-27T22:03:25.191Z",
  "updatedAt": "2026-02-27T22:03:25.191Z",
  "deletedAt": "2026-02-27T22:03:25.191Z"
}

Get map completion progress

get

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

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Map ID

Responses

200

Map progress

application/json

mapIdintegerOptional

mapTitlestringOptional

totalPinsintegerOptional

visitedPinsintegerOptional

completionPercentagenumberOptional

visitedPinIdsinteger[]Optional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/maps/{id}/progress

HTTPcURLJavaScriptPython

GET /api/maps/{id}/progress HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "mapId": 1,
  "mapTitle": "text",
  "totalPins": 1,
  "visitedPins": 1,
  "completionPercentage": 1,
  "visitedPinIds": [
    1
  ],
  "pins": [
    {
      "pinId": 1,
      "order": 1,
      "title": "text",
      "visited": true,
      "visitedAt": "2026-02-27T22:03:25.191Z"
    }
  ]
}

Reset map visit progress

post

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

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Responses

200

Progress reset successfully

application/json

successbooleanOptional

deletedVisitsintegerOptional

messagestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

post

/maps/{id}/reset

HTTPcURLJavaScriptPython

POST /api/maps/{id}/reset HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "deletedVisits": 1,
  "message": "text"
}

Add pin to map

post

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Body

application/json

pinIdinteger · min: 1Required

orderintegerOptionalDefault: 0

Responses

201

Pin added to map

application/json

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

post

/maps/{id}/pins

HTTPcURLJavaScriptPython

POST /api/maps/{id}/pins HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "pinId": 1,
  "order": 0
}

{
  "mapId": 1,
  "pinId": 1,
  "order": 1
}

Remove pin from map

delete

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Query parameters

pinIdintegerRequired

Responses

200

Pin removed from map

application/json

messagestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

delete

/maps/{id}/pins

HTTPcURLJavaScriptPython

DELETE /api/maps/{id}/pins?pinId=1 HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text"
}

Update pin order in map

patch

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Body

application/json

pinIdinteger · min: 1Required

orderintegerRequired

Responses

200

Pin order updated

application/json

mapIdintegerOptional

pinIdintegerOptional

orderintegerOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

patch

/maps/{id}/pins

HTTPcURLJavaScriptPython

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

{
  "pinId": 1,
  "order": 1
}

{
  "mapId": 1,
  "pinId": 1,
  "order": 1
}

Get users a map is shared with

get

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Responses

200

List of share records

application/json

idintegerOptional

mapIdintegerOptional

userIdstringOptional

canEditbooleanOptional

sharedAtstring · date-timeOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/maps/{id}/share

HTTPcURLJavaScriptPython

GET /api/maps/{id}/share HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": 1,
    "mapId": 1,
    "userId": "text",
    "canEdit": true,
    "sharedAt": "2026-02-27T22:03:25.191Z"
  }
]

Share map with a user

post

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Body

application/json

userIdstring · min: 1Required

canEditbooleanOptionalDefault: false

Responses

201

Map shared successfully

application/json

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

post

/maps/{id}/share

HTTPcURLJavaScriptPython

POST /api/maps/{id}/share HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "userId": "text",
  "canEdit": false
}

{
  "id": 1,
  "mapId": 1,
  "userId": "text",
  "canEdit": true,
  "sharedAt": "2026-02-27T22:03:25.191Z"
}

Unshare map with a user

delete

Authorizations

BearerAuth

AuthorizationstringRequired

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

Path parameters

idintegerRequired

Query parameters

userIdstringRequired

Responses

200

Map unshared

application/json

messagestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

404

Resource not found

application/json

500

Internal server error

application/json

delete

/maps/{id}/share

HTTPcURLJavaScriptPython

DELETE /api/maps/{id}/share?userId=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text"
}