API Endpoints
Full API endpoint documentation
API Base URL
All API requests should be made to:
https://api.taglogger.comTags (scope: read:tags; /location and /history also require read:locations)
GET /v1/tags— List and filter tags (optional query:limit,cursor,search, or exactlabel; server-side filters support up to 1,000 visible tags per key scope)GET /v1/tags/{tagId}— Get a single tagPATCH /v1/tags/{tagId}— Change the display name, replace labels, activate/deactivate, or pause/resume alerts and new recording (scope:manage:tags)GET /v1/tags/{tagId}/location— Get current locationGET /v1/tags/{tagId}/history— Get location history (optional query:start,end,order,limit,cursor)GET /v1/tags/{tagId}/battery— Get coarse battery status (scope:read:tags)
Labels are workspace-defined words or identifiers used for display and lookup. Exact label filters are case-insensitive; search also matches the display name, tag id, read-only originalPhysicalLabel, system-provided hardwareId, and labels; terms shorter than 4 characters match only the display name, original physical label, and labels, so a short numeric label search is not swamped by opaque identifiers. The original physical label records the text used when TagLogger originally shipped or provisioned the tag and may be null for older tags. It does not change when a later sticker changes and cannot be changed through PATCH. Neither it nor labels change hardware binding, ownership, member access, or shared-page membership.
Fleet (scope: read:locations)
GET /v1/fleet/delta— Efficient fleet synchronization (optional query:since,limit,cursor)
Geofences (read: read:geofences; create/update/delete: manage:geofences)
GET /v1/geofences— List all geofences (optional query:limit,cursor)POST /v1/geofences— Create a geofencePOST /v1/geofences/bulk— Create 1 to 450 geofences in one transaction, all or none (optional header:Idempotency-Key)GET /v1/geofences/{geofenceId}— Get a single geofencePATCH /v1/geofences/{geofenceId}— Update a geofenceDELETE /v1/geofences/{geofenceId}— Delete a geofenceGET /v1/geofences/{geofenceId}/visits— Each tag's visits to the geofence in a past window, with entry and exit times and time inside, a page of tags at a time (scopes:read:geofencesandread:locations; optional query:from,to,tagIds,limit,cursor)
A geofence is a circle (center and radiusMeters), a polygon (type: "polygon" with 3 to 500 vertices), or a corridor (type: "corridor", a path of 2 to 1,000 points and a widthMeters band from 500 to 20,000 m, default 1,000). A request without type is a circle. Responses always include type; for a polygon or corridor, center is a point on the shape for map labels and radiusMeters is null. Leaving a corridor is a route deviation and fires its exit alert. A PATCH without type edits the current shape and must fit it: center and/or radiusMeters on a circle, vertices on a polygon, path and widthMeters together on a corridor. A PATCH with type and that shape's fields replaces the shape whole. Anything else, such as center on a polygon or a field of another shape beside type, is 400 invalid_geofence. A PATCH that changes nothing returns the geofence as it is. A shape error also carries error.details.reason, for example self_intersecting or too_small (see Errors). The workspace comes from the API key: a create body or bulk item with ownerId, userId or workspaceOwnerUid, whatever its value, is 400 invalid_request.
Bulk create checks every item like a single create and saves all of them or none in one transaction; an error names the failing item as geofences[<index>]. Items that together take more than 4 MiB as JSON return 413 payload_too_large; send fewer geofences per request. Visits are worked out from the recorded positions with the same rules as the alerts, for circles, polygons and corridors alike. The window defaults to the 7 days before to (default now), must start in the past, and can span at most 400 days. tagIds optionally narrows the result to 1 to 100 comma-separated ids; a named tag the geofence does not target has no entry. Visits come a page of tags at a time: limit is tags per page (default 10, at most 100), and while the response's nextCursor is not null, send it as cursor with the same from, to and tagIds (the from and to the first page returned, if you left them out); another window or tagIds returns 400 invalid_cursor. Tags come in tag id order, as GET /v1/tags lists them, and a page can hold fewer than limit tags and still have a next page. A page whose window holds too many recorded locations returns 422 window_too_large; choose a shorter window or a smaller limit. Visits need the geofence time report on the workspace; without it the endpoint returns 403 feature_not_enabled. A report that takes over 75 seconds, or a workspace whose history is still being prepared, returns 503 service_unavailable with Retry-After: 30.
Any geofence write can return 503 service_unavailable when the geofence store did not answer (the write may have landed), with Retry-After: 30. Send the request again after that many seconds. With an Idempotency-Key, retrying a create or bulk create after service_unavailable is safe: the same key and body return the same geofences and never write them twice. Without a key, list geofences before retrying a create. A bulk create is one transaction, all or nothing.
API geofences use the same configuration as the dashboard: color, confirmation checks, entry/exit, dwell, email recipients, push, and existing Slack/Teams/Discord/Telegram/generic integration bindings. Use GET /v1/integrations to discover redacted binding IDs; credentials are never returned.
Setting or clearing To/CC email recipient lists, including the deprecated emailAddress alias, additionally requires read:locations. Alert emails contain the tag's event coordinates even when the Open Map button is disabled.
A tag-scoped key may create geofences only for tags in its scope and may update or delete an existing geofence only when all of that geofence's current target tags are in scope. Managing an all-tags geofence requires an all-tags key.
Customer Pages (read: read:customer-pages; writes: manage:customer-pages)
GET /v1/customer-pages— List Customer PagesPOST /v1/customer-pages— Create a permanent or expiring multi-tag pageGET /v1/customer-pages/{pageId}— Get one pagePATCH /v1/customer-pages/{pageId}— Update name, tags, expiry, or display featuresDELETE /v1/customer-pages/{pageId}— Revoke a pagePOST /v1/customer-pages/{pageId}/rotate-token— Invalidate the old URL and mint a new oneGET/PATCH /v1/customer-pages/branding— Read or update workspace branding
These are the same Customer Pages used by the dashboard and served at /p/<token>. No API-only pages or customer subdomains are created. A tag may be on only one non-revoked page at a time; an expired page keeps its tags until it is revoked. A page's entry and exit feed only shows events recorded after each tag was added to that page; removing a tag and adding it back later starts a fresh window. The optional features.locationHistory key (default false, requires liveMap) lets page viewers show one tag's map trail at a time, floored the same way.
Display features are liveMap, zones, statusTable, zoneActivity, locationHistory, and labels. Location history and labels default to false and appear on the public page only after the page owner enables them.
Webhooks (scope: manage:webhooks)
Subscriptions receive events for every tag in the workspace: create, update, delete, and rotate-secret require an all-tags key, and subscribing to tag.moved or geofence.* events (creating, re-pointing the URL, widening the event set, or re-activating such a subscription) also requires read:locations. Listing, reading, deactivating, testing, and delivery history work with any manage:webhooks key.
GET /v1/webhooks— List subscriptions (optional query:limit,cursor)POST /v1/webhooks— Create subscriptionGET /v1/webhooks/{webhookId}— Get subscriptionPATCH /v1/webhooks/{webhookId}— Update subscriptionDELETE /v1/webhooks/{webhookId}— Delete subscriptionPOST /v1/webhooks/{webhookId}/test— Send a signed test eventPOST /v1/webhooks/{webhookId}/rotate-secret— Rotate the signing secretGET /v1/webhooks/{webhookId}/deliveries— Delivery history: per-event status, attempts, and last error (optional query:limit,cursor)
Share Links (read: read:share-links; create/revoke: manage:share-links)
GET /v1/share-links— List share links (optional query:tagId,limit,cursor)POST /v1/share-links— Mint a public, expiring share link for a tagGET /v1/share-links/{shareLinkId}— Get a single share linkDELETE /v1/share-links/{shareLinkId}— Revoke a share link
A share link is a public URL (/share/<token>) that exposes only one tag's current location to anyone who holds it — the same artifact the dashboard's Share button creates. The tag must be linked to hardware. API-minted links always expire: pass expiresInSeconds or expiresAt, or accept the 90-day default; they can never be set to never-expire. Revoking is a soft delete — the URL stops resolving immediately while access history is retained.
Security Events (scope: read:security-events, all-tags key)
GET /v1/security-events— The workspace's company sign-in security events, oldest first (optional query:since,limit,cursor)
For a SIEM or audit archive: connection, domain, certificate, SCIM token and setup-link changes, member provisioning and removal, denied sign-ins, and policy changes. To collect continuously, keep the last nextCursor and call again with it: you get only events recorded after the previous page. nextCursor is null when nothing newer exists yet; keep the cursor you have and poll again later. since (ISO-8601 or epoch milliseconds) is used only without cursor; an unparseable value returns 400 invalid_since, and a cursor from another endpoint returns 400 invalid_cursor. limit defaults to 100, at most 500. Events are kept 400 days.
Account & Usage (any valid key; no extra scope)
GET /v1/account— Workspace "whoami": the workspace and plan the key resolves to. Stripe identifiers, billing internals, and admin flags are never included.GET /v1/usage— Per-day request counts for the calling key (usage history, not a live rate-limit gauge) (optional query:days— trailing days ending today UTC, default 30, max 40)
For live rate-limit headroom, read the X-RateLimit-* response headers returned on every request rather than calling /v1/usage.
Public (no API key required)
GET /v1/openapi.json— Download the OpenAPI 3.1 spec (public, no API key required)GET /v1/llms.txt— Plain-text API summary for LLM agents (public, no API key required)