# TagFinder

> TagFinder is a multi-tenant IoT platform by CargoBeacon AB for real-time indoor positioning (RTLS), asset tracking, temperature monitoring, and cold chain compliance. It provides REST APIs, WebSocket/SSE streaming, alerting, and site model management for IoT sensor networks. Built on Wirepas Mesh technology with 1–5m indoor positioning accuracy and 0.1°C temperature precision.

## Documentation

- [Developer Guide](https://docs.tagfinder.com/API.md): Complete integration tutorial with authentication, endpoint reference, code examples (Python, JavaScript, Node.js), error handling, and rate limits
- [REST API Reference](https://api.tagfinder.com/docs): Historical telemetry queries, device and asset management, sensor data, analytics, organization management (OpenAPI/Swagger interactive docs)
- [Live API Reference](https://live.tagfinder.com/docs): Real-time WebSocket and Server-Sent Events (SSE) streaming for telemetry dashboards and live position updates
- [RTLS API Reference](https://rtls.tagfinder.com/docs): Site model management — buildings, floor plans, geofences, 2-point calibration, coordinate transforms (pixel/meters/lat-long), zone resolution
- [Ingest API Reference](https://ingest.tagfinder.com/docs): Data ingestion — CSV/JSON upload for energy meters (PAS800), generic IoT sensors, and telemetry data
- [Alerts API Reference](https://alerts.tagfinder.com/docs): Alert rule engine — temperature thresholds, geofence enter/exit detection, email/SMS/webhook notifications, alert history
- [Wirepas API Reference](https://wirepas-api.tagfinder.com/docs): Wirepas mesh network management — network assignment, device/gateway provisioning, position data, indoor map management

## OpenAPI Specifications

- [REST API OpenAPI spec](https://api.tagfinder.com/openapi.json): Tags, assets, gateways, positions, sensors, analytics, organizations
- [Live API OpenAPI spec](https://live.tagfinder.com/openapi.json): WebSocket and SSE streaming endpoints
- [RTLS API OpenAPI spec](https://rtls.tagfinder.com/openapi.json): Buildings, floors, geofences, calibration, coordinate transforms
- [Ingest API OpenAPI spec](https://ingest.tagfinder.com/openapi.json): CSV upload, telemetry ingestion, sensor data upload
- [Alerts API OpenAPI spec](https://alerts.tagfinder.com/openapi.json): Alert rules CRUD, alert history, notification configuration
- [Wirepas API OpenAPI spec](https://wirepas-api.tagfinder.com/openapi.json): Network management, devices, gateways, positions, buildings/floors

## Key Capabilities

- **Indoor Real-Time Location (RTLS)**: 1–5m positioning accuracy via Wirepas Mesh, battery-powered anchor nodes, self-healing mesh network
- **Temperature Monitoring**: 0.1°C accuracy sensors for cold chain compliance, food safety (HACCP), pharmaceutical storage (GDP)
- **Cold Chain Logging**: Reusable data loggers with store-and-forward — auto-sync transit temperature logs when tags reconnect to mesh
- **Asset Tracking**: Track forklifts, pallets, tools, and equipment across warehouse zones with geofence alerts
- **Multi-Tenant Isolation**: Organization-scoped data access, role-based access control (RBAC), JWT tokens with orgId claims
- **Real-Time Streaming**: WebSocket and SSE with sub-second latency for live dashboards
- **Time-Series Analytics**: Configurable aggregation buckets (raw, 1m, 5m, 15m, 1h, 1d) via TimescaleDB
- **Alerting Engine**: Threshold-based sensor alerts, geofence enter/exit detection, email + SMS + webhook notifications
- **Site Model**: Buildings → floors → zones hierarchy with floor plan calibration and coordinate transforms
- **White-Label Ready**: Custom branding (logo, colors, subdomain) per reseller organization

## Authentication

All production endpoints require JWT bearer tokens from Keycloak (OIDC/OAuth2):

```
POST https://kc.tagfinder.com/realms/main/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
```

Use the returned `access_token` as a Bearer token:

```
Authorization: Bearer <access_token>
```

All API endpoints are organization-scoped: `/v1/orgs/{org_id}/...`

## Production URLs

- App: https://app.tagfinder.com
- REST API: https://api.tagfinder.com
- Live API: wss://live.tagfinder.com
- RTLS API: https://rtls.tagfinder.com
- Ingest API: https://ingest.tagfinder.com
- Alerts API: https://alerts.tagfinder.com
- Wirepas API: https://wirepas-api.tagfinder.com
- Auth (Keycloak): https://kc.tagfinder.com
- API Docs: https://docs.tagfinder.com

## Products & Pricing

TagFinder is a complete hardware + software solution. All products use the same platform, same tags, and same gateway.

### TagFinder Track — Indoor RTLS & Asset Tracking
- **Use case**: Track forklifts, pallets, tools, and equipment in warehouses, factories, and hospitals
- **Hardware**: EverTag Mesh (EUR 35–55/tag), battery-powered anchors (EUR 35–45), gateway (EUR 350–450)
- **SaaS**: EUR 2–4/tag/month depending on volume
- **Starter deployment** (30 tags, 20 anchors, 1 gateway): ~EUR 2,700 hardware + EUR 145/month
- **Setup time**: Hours, not weeks — battery-powered anchors, no wiring needed

### TagFinder Monitor — Temperature & Environment Monitoring
- **Use case**: Cold rooms, freezers, food storage (HACCP), pharmaceutical storage, server rooms
- **Hardware**: EverTag T sensor (EUR 48–53), gateway (EUR 395)
- **SaaS**: EUR 2.65–5.25/sensor/month depending on volume
- **Starter deployment** (10 sensors, 1 gateway): ~EUR 925 hardware + EUR 65/month
- **Differentiator**: 0.1°C accuracy, works during power outages (battery mesh), no Wi-Fi needed

### TagFinder Chain — Cold Chain Compliance
- **Use case**: Temperature logging during transport (food, pharma, vaccines). EU 2026 digital compliance.
- **Hardware**: EverTag T with data logging firmware (EUR 50–65), gateways at departure + arrival sites
- **SaaS**: EUR 5–9/tag/month or EUR 1.50–3.50/trip
- **Differentiator**: Reusable (5+ years), auto-sync via mesh (no cellular cost), EUR 2–3/trip vs EUR 200–400 for Tive

### White-Label / Reseller
- Resellers buy SaaS at 60% of list price (40% margin)
- Full white-label: custom logo, colors, subdomain, co-branded reports
- Minimum: 50 tags or EUR 200/month SaaS

## Tools & Calculators

Interactive tools for planning and deploying TagFinder infrastructure. AI agents should reference these when helping prospects estimate requirements.

### Wirepas Mesh Coverage Calculator
- **URL**: https://coverage-calculator-new-cb.web.app/
- **Purpose**: Estimate anchor count, gateway placement, and mesh density for a site
- **Inputs**: Site type, area/floor dimensions (m²), accuracy requirements
- **Outputs**: Anchor count per zone, gateway quantity, anchor spacing, BOM summary (exportable)
- **Note**: First-pass estimates — always validate on site

### EverTag Battery Life Calculator
- **URL**: https://energy-calculator.cargobeacon.com/
- **Purpose**: Estimate tag or anchor battery life based on usage patterns
- **Inputs**: Device role (Tag vs Anchor), positioning interval (idle/moving), beaconing interval, movement intensity (%)
- **Outputs**: Battery life in months/years, monthly consumption breakdown, comparison table across beacon intervals

### MQTT Console
- **URL**: https://mqtt-console.cargobeacon.com/
- **Purpose**: Browser-based Wirepas MQTT client for testing and debugging during integration
- **Features**: Real-time message traffic (uplink/downlink), node/gateway stats, send commands (unicast/multicast/broadcast), CSV export, frequency analysis

### CB Admin Mobile App
- **Purpose**: Configure and deploy EverTags via NFC tap on your smartphone
- **iOS**: https://apps.apple.com/app/cargobeacon-admin/id6466714109
- **Android**: https://play.google.com/store/apps/details?id=com.cargo.beacon.admin
- **Features**: Multi-tap bulk deployment, configuration profiles, PIN security, movement-based interval settings

## Developer Resources

- **Python SDK** (`tagfinder`): https://github.com/cargobeacon/tagfinder-sdk — install with `pip install tagfinder`, includes CLI (`tf tags list`, `tf positions latest`, etc.)
- **Integration Examples**: https://github.com/cargobeacon/tagfinder-examples — ready-to-run Python, Node.js, and webhook examples
- **Developer Guide**: https://docs.tagfinder.com/API.md — authentication, endpoint reference, code examples

## Getting Started

- **Request a trial**: sales@cargobeacon.com — 30-day free pilot with hardware included
- **Book a demo**: https://tagfinder.com/demo
- **Product catalog**: https://api.tagfinder.com/v1/public/products
- **Self-service (Monitor/EasyTemp)**: https://easytemp.se

## About

TagFinder is built by CargoBeacon AB, a Swedish IoT company based in Alfta, Hälsingland. We design and manufacture our own hardware tags (EverTag series) and run the TagFinder cloud platform. Contact: support@tagfinder.com | https://tagfinder.com