RTLS SDK

A Python SDK for the RTLS REST API.

📖 Documentation: https://rtls-sdk.pages.dev

Three-step usage:

from rtls_sdk import RtlsClient

client = RtlsClient.from_env()
tags = client.tags.list()

That's it — token, refresh, scoping headers, 401 re-login are all internal. The first method call performs a lazy login; subsequent calls reuse the session.

What you get

• Compound workflows. One Python call replaces the multi-call REST sagas the JS reference client makes you script — e.g. tags.create(name="X", attached_zone="Z", groups=[...]) runs the three-step create-and-attach with rollback on partial failure.
• One exception hierarchy. Everything under RtlsError: NotFound, ValidationError, RateLimited, ServerError, PartialFailureError, ReportFailed / ReportTimeout, …
• Typed models. Pydantic v2 under the hood; mypy --strict clean out of the box; ships py.typed.
• Mandatory redaction. No password, token, refresh-token, cookie, or Authorization header ever reaches a log handler. There is no opt-out flag.
• Live streaming. client.ws opens a WebSocket subscription and yields typed channel messages (positions, alarms, zone events, …).
• Sync-only for v1. The async surface is on the v2 roadmap.

Install

pip install rtls-sdk

Python 3.10+ supported. See docs/install.md for dev install and verification.

Quickstart

export RTLS_USERNAME="qa@example.com"
export RTLS_PASSWORD="hunter2"
export RTLS_BASE_URL="https://rtls.example.com"

from rtls_sdk import RtlsClient

with RtlsClient.from_env() as client:
    for tag in client.tags.list():
        print(tag.uid, tag.name)

For the full 5-minute walkthrough see docs/quickstart.md.

Documentation

Full documentation: https://rtls-sdk.pages.dev

• Install · Quickstart
• Entity catalog — one page per entity (tags, sites, areas, floorplans, anchors, zones, nodes, users, reports, …) with methods, examples, and model fields.
• Guides — compound workflows, error handling, pagination, rate limiting, scope switching, timestamps, reports, floorplans, credential rotation.
• Advanced — BYO token, raw REST methods, logging, HTTP client override, security.
• Migrating from the JS client, plus an API reference auto-generated from docstrings.

Status

v0.6.2. See CHANGELOG.md for the full release history — including the 0.6.0 breaking changes to the LSB orchestration surface (update → save, no-arg start() / stop() returning bool) and the Association → TagAssociation rename (client.associations is now client.tag_associations).

License

MIT — see LICENSE.