API & Developer Portal
REST API, Python SDK, CLI, WebSocket streaming, and webhook events. Everything you need to build on TagFinder.
TagFinder exposes a family of micro-services — each with its own OpenAPI spec and interactive Swagger UI. Use the Python SDK, the CLI, or call the REST endpoints directly. Everything is multi-tenant, JWT-secured, and versioned.
Quick Start
Install the SDK, set your credentials, and start querying in under 2 minutes.
1. Install
pip install tagfinder # Core SDK pip install tagfinder[cli] # With CLI (tf command) pip install tagfinder[websocket] # With WebSocket streaming pip install tagfinder[all] # Everything
2. Configure
export TF_CLIENT_ID=your_client_id export TF_CLIENT_SECRET=your_client_secret export TF_ORG_ID=your_org_id
3. Use
from tagfinder import TagFinderClient
tf = TagFinderClient() # Uses env vars automatically
# List all tags
tags = tf.tags.list()
for tag in tags:
print(f"{tag.tag_id}: {tag.tag_name} ({tag.status})")
# Query sensor data
data = tf.tags.sensor_data("wirepas:12345", from_time="2026-03-11T00:00:00Z")
for reading in data.readings:
print(f"{reading.timestamp}: {reading.sensor_readings}")
# Get latest positions
positions = tf.positions.latest()
for pos in positions:
print(f"{pos.tag_name} in {pos.zone_name}")REST API
Full CRUD with JWT authentication and OpenAPI 3.0 documentation. Base URL: https://api.tagfinder.com/v1
Authentication
OAuth2/OIDC token flow, API keys, and service accounts.
Assets & Tags
CRUD operations for assets, tags, and tag types.
Sensor Data
Query temperature, humidity, accelerometer, and position data.
Geofences & Zones
Create, update, and query geofence boundaries and events.
Alerts & Webhooks
Configure alert rules and webhook delivery endpoints.
Buildings & Floors
Manage site models, floor plans, and coordinate systems.
Versioning
Semantic versioning. Breaking changes announced 90 days ahead.
Rate Limits
1,000 req/min Starter. 10,000 Professional. Unlimited Enterprise.
Formats
JSON responses. CSV export for reports. Protobuf for streams.
SDK API Coverage
| Sub-client | Service | Operations |
|---|---|---|
| tf.tags | REST API | list, get, update, sensor_data |
| tf.assets | REST API | list, get, create, update, delete, attach_tag, detach_tag |
| tf.positions | REST API | latest, history, asset_position, rtls |
| tf.alerts | Alerts API | list_rules, get_rule, create_rule, update_rule, delete_rule, add_recipient, remove_recipient, history |
| tf.rtls.buildings | RTLS API | list, get, create, update, delete |
| tf.rtls.floors | RTLS API | list, get, create, upload_image, delete |
| tf.rtls.geofences | RTLS API | list, get, create, update, delete |
| tf.ingest | Ingest API | upload_csv, push_sensor_data, push_position |
| tf.wirepas | Wirepas API | list_devices, get_device, list_gateways, latest_positions, position_history |
| tf.live | Live API | stream_telemetry (async), stream_wirepas (async) |
CLI Reference
The TagFinder CLI (tf) lets you manage your installation from the terminal.
tf tags list # List all tags tf tags get wirepas:12345 # Tag details tf tags sensor-data wirepas:12345 --from 2026-03-01 # Sensor data tf positions latest # Latest positions tf assets list # List assets tf assets create --name "Forklift #3" --type vehicle tf alerts list-rules # Alert rules tf alerts history --limit 10 # Recent alerts tf version # SDK version
Installation
pip install tagfinder[cli] or standalone binary.
Configuration
Environment variables or tf config set.
Deployment
Deploy and update services with zero downtime.
Migrations
Run, rollback, and inspect database migrations.
Organizations
Create organizations, invite users, manage roles.
Data Export
Export sensor data, compliance reports, audit logs.
Code Examples
Ready-to-run examples from the tagfinder-examples repository.
Python
| Script | Description |
|---|---|
| 01_quick_start.py | Authenticate, list tags, query sensor data |
| 02_temperature_monitoring.py | Find temp sensors, check thresholds, create alert rules |
| 03_asset_tracking.py | Create assets, associate tags, query positions and zones |
| 04_live_dashboard.py | WebSocket streaming - real-time position updates |
| 05_cold_chain_report.py | Transport temperature compliance check with CSV export |
| 06_geofence_alerts.py | Create geofence zones and enter/exit alert rules |
Node.js
| Script | Description |
|---|---|
| websocket-stream.js | WebSocket position streaming (npm install ws) |
| rest-api-query.js | REST API queries with fetch (Node 18+) |
WebSocket Streaming
import asyncio
from tagfinder import TagFinderClient
async def main():
tf = TagFinderClient(org_id="acme-corp", token="your_jwt_token")
async for update in tf.live.stream_wirepas():
print(f"Tag {update['tag_id']} at ({update.get('x')}, {update.get('y')})")
asyncio.run(main())Advanced Usage
Create Alert Rules
# Temperature alert
rule = tf.alerts.create_rule(
rule_name="Cold room above 8C",
trigger_type="sensor_threshold",
conditions={
"sensor_field": "temperature",
"operator": "greater_than",
"threshold": 8.0,
},
cooldown_minutes=30,
)
# Add email recipient
tf.alerts.add_recipient(
str(rule.rule_id),
recipient_type="email",
recipient_value="ops@acme.com",
)Site Model (RTLS)
# Create building -> floor -> geofence
building = tf.rtls.buildings.create(
name="Warehouse A", latitude=61.347, longitude=16.189
)
floor = tf.rtls.floors.create(
building.building_id, floor_number=1, name="Ground Floor"
)
tf.rtls.floors.upload_image(floor.floor_id, "warehouse_floor1.png")
zone = tf.rtls.geofences.create(
name="Loading Dock",
geofence_type="dock",
floor_id=floor.floor_id,
polygon_local=[
{"x": 0, "y": 0}, {"x": 10, "y": 0},
{"x": 10, "y": 5}, {"x": 0, "y": 5},
],
)Authentication
Client Credentials
Service-to-service authentication. Automatic token refresh. Recommended for backend integrations.
PKCE Flow
For single-page apps and mobile. Secure browser-based authentication without client secrets.
Pre-obtained JWT
Pass an existing token directly. Useful for testing and SSO-federated environments.
# Client credentials (recommended)
tf = TagFinderClient(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
org_id="acme-corp",
)
# Or with a pre-obtained JWT token
tf = TagFinderClient(token="eyJhbGci...", org_id="acme-corp")
# Or via environment variables (simplest)
# export TF_CLIENT_ID=... TF_CLIENT_SECRET=... TF_ORG_ID=...
tf = TagFinderClient()Developer Resources
API Docs Hub
All service specs, developer guide, and llms.txt.
Open →REST API — Swagger
Interactive OpenAPI UI for the main REST API.
Open →Live API — Swagger
WebSocket & SSE streaming endpoints.
Open →Python SDK
pip install tagfinder — full client with async & CLI.
Open →Integration Examples
Python, Node.js, and webhook examples. Ready to run.
Open →EverTag Documentation
Hardware manual for tags and anchors.
Open →