LocationNotes API documentation

Base URL

All examples on this page assume the current production host:

https://locationnotes.com

Format

Requests and responses use JSON. GUIDs are the primary identifiers across notes, categories, teams, and devices.

Authorization

Private, sync, and team endpoints require an `Authorization: Bearer <access token>` header unless the route is marked public below.

Language

Public and management reads can pass `contentLanguage=en-US` or another supported content language to filter the returned note/category content.

{
  "deviceId": "5dd06ca7-34a5-4f2e-812d-3f1ef3e48290",
  "notes": [
    {
      "noteId": "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
      "ownerUserId": "a7cfd28f-c17f-4cf7-8913-47fa10fd0d1f",
      "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
      "title": "Offline inspection",
      "body": "Saved while disconnected.",
      "contentLanguage": "en-US",
      "latitude": null,
      "longitude": null,
      "visibility": "Private",
      "isDeleted": false,
      "updatedUtc": "2026-03-13T20:12:00Z",
      "clientMutationId": "android-offline-42",
      "teamId": null
    }
  ],
  "categories": []
}

{
  "appliedNoteIds": [
    "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb"
  ],
  "appliedCategoryIds": [],
  "conflicts": []
}

{
  "lastSyncUtc": "2026-03-13T19:45:00Z",
  "publicArea": {
    "minLatitude": 41.78,
    "minLongitude": -87.75,
    "maxLatitude": 41.96,
    "maxLongitude": -87.54
  }
}

{
  "serverSyncUtc": "2026-03-13T20:13:02Z",
  "userNotes": [],
  "userCategories": [],
  "teamCategories": [],
  "publicNotes": [],
  "teamNotes": []
}

Read personal notes

Optional query string: contentLanguage and full map bounds with minLatitude, minLongitude, maxLatitude, maxLongitude.

Create a note

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "Category-only feedback",
  "body": "This note stays off the map on purpose.",
  "contentLanguage": "en-US",
  "latitude": null,
  "longitude": null,
  "visibility": "Public",
  "commentPolicy": "LoggedInUsers"
}

Note page reads and actions

{
  "body": "I found it too."
}

{
  "trackableSecretCodes": "LN4C8R2Z",
  "selectedActiveTrackableIds": [
    "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
  ],
  "activeTrackableAttachMode": "Self"
}

These note-page routes respect private-note access. If the caller can open the note page, the API can return comments and visible trackables for that note. Attaching trackables requires the note owner or a team admin.

Read categories

Create or move categories

{
  "name": "Field Reports",
  "contentLanguage": "en-US",
  "parentCategoryId": null
}

Common reads

• GET /api/teams
• GET /api/teams/{teamId}/notes
• GET /api/teams/{teamId}/categories
• GET /api/teams/{teamId}/categories/tree
• GET /api/teams/{teamId}/invite-links

Create a team

{
  "name": "beta-testers",
  "title": "Beta Testers",
  "description": "Public beta release gate for Android validation.",
  "joinPolicy": "RequestsAllowed",
  "pageVisibility": "Public",
  "defaultNoteVisibility": "Public",
  "contentLanguage": "en-US"
}

Create a team note

{
  "categoryId": "68cb4c9b-d9bd-4bde-8c6a-a03a4c70b283",
  "title": "Shared dock inspection",
  "body": "Visible to the team until we publish it.",
  "contentLanguage": "en-US",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private",
  "commentPolicy": "TeamMembers"
}

Membership and invite operations

• POST /api/teams/{teamId}/memberships/request
• POST /api/teams/{teamId}/memberships/invite
• POST /api/teams/{teamId}/memberships/{membershipId}/accept
• POST /api/teams/{teamId}/memberships/{membershipId}/refuse
• POST /api/teams/{teamId}/memberships/{membershipId}/approve
• POST /api/teams/{teamId}/memberships/{membershipId}/deny
• POST /api/teams/{teamId}/memberships/{membershipId}/promote-admin
• DELETE /api/teams/{teamId}/memberships/{membershipId}
• POST /api/teams/invite-links/{teamSlug}/{inviteCode}/join

Identifier formats and examples

Generated public-code tokens and generated short-secret bodies use the same smudge-resistant character family. Typed lookup treats O like 0, I or L like 1, S like 5, and U like V. For system short-secret codes, that normalization applies to the generated body after the literal prefix. Public codes use that same configured prefix with a dash before the generated body, so they are visually distinct from short secret codes.

List and detail reads

• GET /api/trackables/public
• GET /api/trackables/mine
• GET /api/trackables/{trackableId}
• GET /api/trackables/profile/{userName}/{publicCode}
• GET /api/trackables/team/{teamSlug}/{publicCode}
• GET /api/trackables/{trackableId}/journey

Create one trackable

{
  "name": "Promo coin",
  "description": "Launch event inventory item",
  "teamId": null,
  "isPublic": true,
  "activateImmediately": false,
  "secretCode": ""
}

{
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "heading": "Unactivated Trackable",
  "description": "Please activate this trackable item",
  "items": [
    {
      "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
      "name": "Unactivated Trackable",
      "publicCode": "LN-7K4V9T",
      "secretCode": "LN4C8R2Z",
      "scanUrl": "https://locationnotes.com/trackable/ABCD...<100 characters total>...",
      "qrPayload": "https://locationnotes.com/trackable/ABCD...<100 characters total>..."
    }
  ]
}

Bring your own secret code

{
  "name": "Marketing token",
  "description": "Bring-your-own identifier",
  "teamId": null,
  "isPublic": false,
  "activateImmediately": true,
  "secretCode": "TAG42"
}

The server accepts caller-supplied secret codes that do not start with LN or GT and do not match any existing secret or public code. The returned public code is still system-generated.

Create a group

{
  "name": "Gnomes in this hunt",
  "description": "Seasonal hunt inventory",
  "defaultTrackableTitle": "",
  "defaultTrackableDescription": "",
  "trackableCount": 12,
  "teamId": null,
  "isPublic": true,
  "activateImmediately": false
}

Groups are limited to 100 trackables. Unactivated items fall back to the group defaults until activation. Once activated, they must use their own title and description.

Lookup and active session

• POST /api/trackables/lookup matches a public code token or short secret code after normalizing the common smudged-character substitutions listed above.
• GET /trackable/{code} is the short website entry route. It accepts a public code, a short secret code, or the long QR token and then routes to the correct flow.
• GET /api/trackables/active lists the client's currently active secret-code sessions.
• GET /api/trackables/active/{trackableId} returns the active landing payload, including activation requirements and grouped items when available.
• POST /api/trackables/active/{trackableId}/message updates the remembered status text.
• DELETE /api/trackables/active/{trackableId} ends the remembered secret-code session on that client.

Secret-code lookups and private scan-QR visits create an active client session instead of returning the secret value. That active session is what lets later note flows attach the trackable without re-entering the code.

A bare public-code lookup is safe because short public codes are globally unique. The website also accepts the short direct route forms /trackable/{publicCode}, /trackable/{secretCode}, and /trackable/{qrToken}.

That distinction also applies on note pages: a public code is for opening the public trackable page, while note attachment expects an existing short secret code or an already-active browser session.

GET /api/trackables/lookup?code=LN4C8R2Z

{
  "found": true,
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "isPublicCodeMatch": false,
  "usesSecretAccess": true,
  "redirectUrl": "/en-US/trackables/active/f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
}

GET /trackable/LN-7K4V9T

GET /api/trackables/profile/alex/LN-7K4V9T

GET /api/trackables/team/beta-testers/LN-7K4V9T

GET /trackable/ABCD...<100 characters total>...

Activate to self or team

{
  "name": "Bramble the Mossy Wanderer",
  "description": "A small green gnome ready for the next stop.",
  "teamId": "optional-team-guid"
}

If teamId is supplied, the trackable becomes team-owned, team admins can manage it, and the activating member keeps control while they remain on that team. Without teamId, the trackable becomes personally owned.

For group-created unactivated items, activation is also the step where the new owner must choose the final item-specific title and description.

Detach and reattach groups

• DELETE /api/trackables/{trackableId}/group removes the current group association.
• POST /api/trackables/{trackableId}/group with { "trackableGroupId": "..." } associates a detached trackable with a new group.

A trackable can only belong to one group at a time. The server enforces the detach-first rule. Only the original activator can reattach a detached trackable, and the destination group must also be controlled by that user or an eligible team admin.

{
  "trackableGroupId": "4bdffcab-bb51-4fd8-8c15-59f7b2d72c3f"
}

Trackable comments

• GET /api/trackables/{trackableId}/comments
• POST /api/trackables/{trackableId}/comments

Clients must be logged in to post comments. Unactivated trackables cannot be commented on.

{
  "body": "Starting the route now."
}

Visibility and journey disclosure

Trackable journey pages may show mapped locations even when some underlying notes are private. In those cases, unauthorized viewers can receive the location point but not the protected note content.

Authorized viewers receive the note title, description, and note link directly from the preloaded journey payload and map pin popups.

Deletion and retention

Deleting one account does not automatically delete every trackable that account ever touched. Shared or team-owned trackables can remain while only the deleted user's removable personal activity is removed.

Review the Delete Data page and the account-delete API section for the current retention boundaries.

Use this for health checks, Android compatibility gating, and the current beta-page URL.

Returns staged Android beta metadata, including display version, version code, minimum compatible version, and release notes.