Waymark Smart Tag API Documentation

Base URL: https://api.waymark-trace.com/v1

Auth: Bearer Token via Authorization: Bearer <JWT>

1. Update Tag Display

Updates the E-ink screen with specific traveler or destination details. This is typically triggered by an itinerary change.

Endpoint: POST /locations/display

Description: Pushes new text/metadata to the Waymark hardware via the Location Details API.

Request Body:

{
  "tag_id": "WM-9982X",
  "display_mode": "itinerary_active",
  "content": {
    "header": "Arriving: Grand Hyatt Tokyo",
    "sub_text": "2-10-3 Roppongi, Minato City",
    "contact_phone": "+81 3-4333-1234",
    "privacy_lock": true
  }
}

Success Response: 200 OK – Display refresh queued.

2. Log Transit Event

Logs a "breadcrumb" whenever a bag passes a verified hub (Airport, Hotel, Office).

Endpoint: POST /api/locations

Description: Used by the tag hardware or hub-scanners to register a verifiable breadcrumb trail using the Location Management API.

Request Body:

{
  "tag_id": "WM-9982X",
  "event_type": "CHECK_IN",
  "location_id": "HND-TERMINAL-3",
  "timestamp": "2026-01-20T12:00:00Z",
  "metadata": {
    "battery_level": "88%",
    "signal_strength": "-65dBm",
    "hub_type": "airport"
  }
}

Success Response: 201 Created – Location event logged to the ledger.

3. Proximity Hub Search

Finds the nearest authorized return centers if a bag is flagged as "lost."

Endpoint: GET /locations/search

Description: Queries the database for the nearest recovery points using the Locations Search API.

Query Parameters:

• lat (float): Current latitude of the mobile app.

• lng (float): Current longitude of the mobile app.

• type (string): Filter by lost_and_found, courier_hub, or office.

• radius_km (int): Search distance.

Example Request: GET /locations/search?lat=35.66&lng=139.73&type=courier_hub&radius_km=10

Success Response (JSON):

{
  "results": [
    {
      "name": "Global Logistics Hub - Roppongi",
      "distance_km": 1.2,
      "address": "6-chōme-10-1 Roppongi",
      "operating_hours": "24/7",
      "authorized_agent": true
    }
  ]
}

Error Codes