Trackable API Flow

Anonymous secret-backed flow

Use this guide when the caller will not sign in but either has this browser's active trackable session or physically holds the trackable's exact short secret code or private QR token and needs to leave a location update or comment right away.

Follow the sequence Authenticated flow Error reference Main API docs

Core rules

The trackable must already be activated. Unactivated items reject comments and journey-stop writes.
Every anonymous write must come from this browser's active trackable session or include the exact access credential for that specific trackable.
The access credential may be the short secret code, the raw QR token, or the full /trackable/{code} URL.
Anonymous posts are add-only for the person who created them. Only the trackable owner or current team admins can remove them later.
Trackable owners and current team admins can moderate by deleting a comment or journey stop, but they cannot edit somebody else's content.

Step 1: Resolve or visit the trackable

An anonymous caller can still read public-safe trackable data and journey points before posting.

POST https://www.locationnotes.com/api/trackables/lookup
Content-Type: application/json

{
  "code": "LN4C8R2Z"
}

If the code is a short secret or QR token, the browser gains an active secret-backed session. API writes can use that active session, or the caller can resend the access code when needed.

Step 2: Read the current public-safe state

GET https://www.locationnotes.com/api/trackables/{trackableId}
GET https://www.locationnotes.com/api/trackables/{trackableId}/journey
GET https://www.locationnotes.com/api/trackables/{trackableId}/comments

The comments payload tells an anonymous client that posting is allowed, whether the browser already has active access, and that anonymous posts can only be removed later by the trackable owner or current team admins.

Journey reads expose the saved stop plus currentNotesAtCoordinate. That collection is today's visible note read model for the same coordinate, not proof that the stop permanently owns one note.

Step 3: Post an anonymous comment

POST https://www.locationnotes.com/api/trackables/{trackableId}/comments
Content-Type: application/json

{
  "body": "Saw it at the reception desk.",
  "accessCode": "LN4C8R2Z"
}

If the caller omits the code entirely and the browser is not already carrying an active session for that same trackable, the API returns a forbidden problem-details response with code: "trackable_access_code_required". If the code belongs to another trackable or is malformed for this item, the response uses trackable_access_code_invalid.

Step 4: Post an anonymous direct map report

POST https://www.locationnotes.com/api/trackables/{trackableId}/journey-stops
Content-Type: application/json

{
  "latitude": 41.881832,
  "longitude": -87.623177,
  "accessCode": "https://locationnotes.com/trackable/ABCD...<raw or full URL>"
}

This is the lightweight map-first flow. The stop is stored directly on the trackable journey without creating a note. If the person later signs in and wants richer note content, the website can send them into the note-creation flow from that stop.

Friendly client messaging

The anonymous flow works best when the client explains the limitation without sounding threatening. A good pattern is:

You can post this without an account.
Anonymous updates can't be edited or removed later,
but the trackable owner or team admins can moderate them if needed.

If the user does want future editing or note conversion, offer a secondary action like Login to leave a note instead of forcing sign-in up front.

After posting

Refresh the journey and comments endpoints so the client can show the newly posted stop or comment immediately.

GET https://www.locationnotes.com/api/trackables/{trackableId}/journey
GET https://www.locationnotes.com/api/trackables/{trackableId}/comments

Moderation and cleanup

Anonymous comments and anonymous journey stops are still tied to a specific trackable because every write is authorized by that trackable's active session or access credential.
Exports include those records with explicit anonymous/authenticated flags.
Trackable exports and retention flows may keep saved stop snapshots and note-link records as separate facts so later note edits do not rewrite earlier route history.
If a bad actor emerges, owners and current team admins can remove the affected records permanently.

When the caller is ready to own or edit what they post, move them to the authenticated trackable flow. For negative responses, use the trackable error reference.