Build with Telematric APIs.

One workspace for your application's device data, supported source connections and AI operations. Your backend holds the API key; your application keeps its users, interface and business logic.

Hardware SDKs and software connectors are setup choices. A workspace is the ownership boundary; a service enables operations; scopes restrict each key. A service marked Available still needs activation where required. Read requirements and pricing before checkout.

New workspaces use one platform plan when plan enrollment is enabled. Existing workspaces retain their legacy service subscriptions until an explicitly reviewed migration.

All plans include Device cloud plus basic temperature/humidity, water and energy readings. Compatible commands, ESP32 OTA, alerts and webhooks are included. Hardware requirements and API scopes remain unchanged. Physical development devices can use verified sandbox subscriptions while sandbox billing mode is selected.

Starter includes 1 Standard software connection, Growth 3 and Scale 10. Admin classifies each working connector as Standard or Enterprise and configures its individual monthly price. Standard connectors use included capacity or their own paid subscription when the allowance is full. Enterprise connectors require a separate subscription even with spare Standard capacity. Source licences and API fees remain separate. Existing subscriptions and enabled connection classifications retain their saved agreements. Additional flat-slot sales are retired; earlier paid flat slots only add Standard capacity. Energy forecasting & planning and Water records, metering & tariffs are monthly workspace add-ons. Current prices and connector classifications are configured in Administration and returned by GET /v1/public/config; use the workspace quote before checkout. See current pricing. One current source configuration per connector type is supported. Extra slots do not enable multiple installations of the same provider yet. GET /v1/organizations/{org}/connectors returns connection_slots. A successful Standard configuration save claims included capacity when eligible; Enterprise requires its paid subscription. Quotes return expected_connector_revision and expected_connector_tier; pass both with the quoted amount/mode to checkout. Changing an admin category affects new or released-and-resaved configurations; enabled connections retain their billing classification. A successful configuration save is atomic; failed validation or stale revisions do not. POST /v1/organizations/{org}/connectors/{provider}/release-slot releases capacity without deleting retained data or cancelling a paid slot. Re-save the configuration to reconnect. Cancelling a connector subscription stops renewal; verified prepaid access remains until its paid period ends. Connections exceeding capacity then stop operating, in allocation order. Provider-specific subscriptions retain their saved rates and do not consume included Standard slots while paid. Source-system licensing, permissions and installation acceptance are separate. AI personalization is a separately priced gated capability; paid activation is not yet available.

Measure the actual usage

Registered-device limits include disabled registrations. One telemetry unit is one accepted timestamped reading up to 2 KiB of canonical JSON (event ID, UTC recorded time and normalized metrics), rounded up for larger readings. Identical accepted telemetry retries reuse the existing reading and do not consume another telemetry unit. API-key requests remain a separate shared workspace counter; authorized requests can count even if a later validation or upstream operation fails. The per-key minute limit still applies.

API counters reset at the UTC calendar-month boundary, not the subscription anniversary. Plan purchase does not reset existing usage. Monthly API/telemetry caps reject additional workload with 429; device registration above the allowance returns 409. No capacity pack or overage is charged automatically. Owner/admin account sessions can still manage Billing and keys when an API-key quota is exhausted. Full workspace exports remain support-assisted.

Use the same quote in your application

Platform administrators set monthly USD plan/add-on offer prices. Price changes affect new checkouts; existing subscriptions and earlier pending orders retain their saved amounts. New checkout can be disabled without revoking already-paid access. A stale quote returns 409; refresh the quote, or resume an earlier pending checkout from Billing. Capacity limits are independent of price edits.

GET /v1/organizations/{org}/services includes pricing_model, active_plan and service rows. Plan workspaces receive plan/add-on offers and bundled feature access. Legacy workspaces retain service offers and saved rates. A billing quote for a plan workspace uses contract_version: 2; legacy quotes remain version 1.

GET /v1/organizations/{org}/billing/quote?service_id=plan_starter&gateway=bachs
X-API-Key: YOUR_WORKSPACE_KEY_WITH_BILLING_READ

Use IDs plan_starter, plan_growth, plan_scale, addon_sap, addon_maximo, addon_giswater, addon_senaite, addon_lims, addon_energy or addon_water. Quote access accepts billing:read or an owner/admin session. Checkout remains owner/admin-session-only and requires accept_recurring: true, the selected gateway and the current expected amount/mode returned by the quote. USD plan checkout uses Bachs when configured; Paystack continues to support configured legacy NGN offers.

Renewal, expiry and migration

Only one effective base plan is supported. Resolve a pending plan checkout in Billing before starting another. Plan changes are support-assisted; do not buy a second plan to upgrade. Add-ons require a paid base plan in the same environment; live access takes precedence over sandbox access. An add-on grants no access after the base plan expires.

Stopping plan renewal also requests cancellation of active add-on renewals in that environment. Provider failures remain visible and must be retried; the renewal-review worker reconciles cancelled/expired parents. Paid access remains through the verified paid period. Conflicting verified plan payments are recorded for support review and do not grant a second effective plan.

GET /v1/organizations/{org}/billing/migration-preview is owner/admin-only and read-only. It shows the current pricing model, saved subscriptions and grants. It does not change prices, cancel renewals or convert a workspace. Existing customer migration needs separate review and agreement. Retention, aggregate, snapshot/egress packs and physical-trial targets in the roadmap are not implemented plan guarantees.

Build against our equipment and assets API using synthetic data. No SAP or IBM account, installation or connector credentials required.

1. Create your Telematric account and workspace. Verify your email if requested.
2. On Overview, choose Try equipment sandbox and run a sample request.
3. Open API keys and choose Create sandbox key. It selects only sandbox:read; save the secret securely on your server.
4. Use your workspace ID and key in the request below. No service subscription or vendor credentials are required for synthetic data.

In Dashboard → Integrations, select SAP or IBM Maximo and choose Try Telematric sandbox. For your own backend, create a workspace API key with sandbox:read for synthetic data only. Existing keys with both connectors:read and assets:read also work. Keep this key on your server. Workspace access and normal API limits still apply.

curl 'https://telematric.com/v1/organizations/YOUR_WORKSPACE_ID/sandbox/connectors/sap/assets?limit=2&page=1' \
  -H 'X-API-Key: YOUR_TELEMATRIC_WORKSPACE_KEY'

Replace sap with ibm for Maximo assets. GET /v1/organizations/{org}/sandbox/connectors lists sandbox resources. Responses contain records (external_id, name, source_fields), pagination, source_identity, fetched_at, environment: telematric_sandbox, synthetic: true and dataset_version: assets-v1.

Six stable sample assets per provider span industrial, building, energy and distribution equipment. Set limit (1–100), page (starting at 1), or external_id for an exact lookup. SAP starts at SBX-EQ-001; Maximo starts at SBX-AS-001 in site SBX-SITE, organization SBX-ORG. SAP’s current equipment profile does not supply a plant/site; applications must map that explicitly.

Add scenario=empty for an empty collection, scenario=rate_limit for HTTP 429, or scenario=unavailable for HTTP 503. Simulated errors include retry_after_seconds: 5 and a Retry-After: 5 header. Unknown scenarios return 422; invalid authentication and permissions return real access errors before any simulation.

Location and work-order previews use the same paths ending in /locations or /work-orders, with dataset_version: eam-v1. All resources include a vendor-neutral canonical object so applications do not need SAP/Maximo field translation. These previews stay outside operational permit workflows.

This is a read-only Telematric fixture service. It does not contact SAP/Maximo, create identity links, import assets or simulate payments or safety approvals. Keep synthetic data out of operational equipment and permit workflows. SAP’s own API-key sandbox is a separate provider service.

When ready for customer data, create and verify their connector in the dashboard, then explicitly switch to /v1/organizations/{org}/connectors/{provider}/assets. Keep sandbox and customer records separated by source identity and environment. Successful sandbox tests do not validate a real customer installation.

Read equipment and asset records from your own SAP S/4HANA or IBM Maximo installation, then link their identities to Telematric sites and devices.

Read-only pilots: customer installation validation is pending. Configure your API URL, dedicated credentials, product version and source scope in Dashboard → Integrations. SAP uses the API_EQUIPMENT OData V2 profile with Basic access for customer systems, or API-key access for SAP sample sandboxes and compatible equipment API gateways. Select the sandbox environment for sample data. Maximo uses MXAPIASSET with an API key and an explicit organization/site. Bounded read-only location and work-order endpoints are also available under /locations and /work-orders; the customer source must grant access to those resource profiles. Source edits, safety-status delivery, full inventory synchronization and connector fees are outside these profiles.

Use GET /v1/organizations/{org}/connectors/sap/assets?limit=25&page=1 or replace sap with ibm for Maximo. Backend keys need connectors:read and assets:read; managers use connectors:manage and assets:manage. Optional external_id filters one equipment identity. Responses include source identity, fetch time and bounded pagination.

Dedicated readers retain source-system authorization rules. Product versions are declared by your IT team, not automatically certified. Sandbox checks validate SAP sample data and do not certify a customer installation. Internal-only deployments need an approved connectivity arrangement; do not expose your ERP publicly to use this form.

Configure an asset pilot ↗

Link existing customers, hand off an authorized lead and follow its sales progress.

In Integrations → Odoo CRM, configure Odoo 19 JSON-2 API access, the explicit database/company and a dedicated API key. Odoo Online requires a plan with external API access. Start with read access; enable explicit creation only when your application needs lead handoff. Odoo retains stages, assignments and business automation.

API base: /v1/organizations/{org}/connectors/odoo. Read scopes: connectors:read + crm:read. Manage settings/mappings: connectors:manage + crm:manage. Queuing/processing handoffs additionally requires crm:write. CRM works independently of Device cloud and Water records.

GET /browse/customers and GET /browse/leads accept limit/offset. Use shared /mappings to link explicit source customer/lead IDs with existing Telematric customers/sites/devices. No customer matching by name or automatic customer duplication.

POST /v1/organizations/{org}/connectors/odoo/handoffs
{
  "external_key": "enquiry-1234",
  "name": "Customer enquiry",
  "description": "Details from your application",
  "type": "lead",
  "partner_id": 7,
  "create_confirmed": true
}

Queuing explicitly authorizes scheduled delivery. Reusing the same reference and details is idempotent. POST /handoffs/{id}/sync processes or reconciles a request; GET /handoffs shows status/freshness and GET /handoffs/{id}/revisions preserves changed status history. Odoo standard external IDs support reconciliation without custom fields. An uncertain outcome triggers reference lookup, not blind creation retries. Source edits remain owned by the CRM.

No invoice, payment, maintenance or automatic alert-to-sales workflow is included. Zoho CRM is the next connector on this path; its dashboard listing currently collects interest.

Read Giswater nodes, pipes, service connections and DMAs through your Telematric backend.

Tested with Giswater API 1.8.1 and a WS 4.17.6 database. The connector accepts DB 4.17.x with HTTP Basic access. In Integrations → Giswater, save the public HTTPS tenant API URL, explicit project schema and dedicated reader credentials, then test the connection. Configure the reader’s project selections in Giswater.

API base: /v1/organizations/{org}/connectors/giswater. Reads require connectors:read and gis:read; management requires connectors:manage and gis:manage. GIS works independently of Device cloud, Metering and laboratory services.

Browse and track explicitly

GET /browse/{kind}?limit=10 reads a bounded source list for node, arc, connec or dma. Optional dma_id filters a selection. Source feature lists have no offset pagination and are never treated as a complete inventory. Coordinates retain the project EPSG; transform them explicitly before using a WGS84 map.

POST /records with {"record_kind":"node","external_id":"1001"} tracks an identity. Then POST /records/{id}/sync fetches and validates it. Use GET /records for paginated metadata, GET /records/{id} for the cached snapshot and freshness, and GET /records/{id}/revisions for history. Failed reads preserve prior snapshots and mark them noncurrent.

Scheduled refreshes process only explicitly tracked records. Use shared /mappings to link source assets to your sites/devices or optional laboratory sampling points. Project changes invalidate old links. Telematric does not edit networks, run hydraulic models or infer missing assets from limited lists.

A consistent connector contract for your own backend and dashboard.

GET /v1/organizations/{org}/connectors returns contract version 1, provider capabilities, configuration revision, safe connection health and service access. Use connectors:read; provider operations also require the relevant provider scopes. SENAITE, read-only Giswater and Odoo CRM use this foundation; other listed providers remain on the roadmap.

Owners and administrators can open Integrations to inspect the SENAITE connection, test it and manage explicit site/device identity links. The existing laboratory setup and result synchronization remain available. Connection verification alone does not establish result freshness.

Connection and identity APIs

Under /connectors/senaite, use /connection to read/save the existing encrypted configuration, /verify to test a revision, /mappings to list/create links, /mappings/{id} to revise a link, and /events for manager audit history. Writes require connectors:manage and water-labs:manage; mapping reads require connectors:read and water-labs:read. Water records must be enabled; Device cloud, native Metering and Billing are independent.

Mappings link explicit source sample UIDs to existing Telematric site/device IDs. They do not import results or verify a source sample exists. Source installations retain record ownership; changing an installation invalidates its old links until deliberately replaced. Existing laboratory sample mapping and publication checks still control result imports.

POST /v1/organizations/{org}/connectors/senaite/mappings
{
  "external_type": "sample",
  "external_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "target_type": "site",
  "target_id": "YOUR_SITE_UUID",
  "mapping_confirmed": true
}

Lists use limit and offset. Mapping updates require expected_revision, enabled, target_id and explicit confirmation. Existing SENAITE APIs remain compatible. Full source APIs remain accessible directly with the appropriate permissions for capabilities beyond our connector.

Configure and test a dedicated SENAITE account from Water records → Laboratory connection, or use your own backend and dashboard. Requires Water records access and an owner/admin session or an API key with water-labs:manage. Device cloud, native Metering and Utility billing are independent.

Use GET or POST /v1/organizations/{org}/water-data/laboratory-connection to read metadata or save api_url, username, password and integer expected_revision (zero initially). Passwords are encrypted and never returned. The URL must end in /@@API/senaite/v1 on a public HTTPS site.

Call POST /v1/organizations/{org}/water-data/laboratory-connection/verify with the current expected_revision. Verification checks the authenticated account and API version. Each completed test increments the revision; reload settings after failure. A verified status describes the last connection test only.

Choose who operates SENAITE

Your installation: your team operates SENAITE and provides a dedicated read account. Partner laboratory: your lab partner operates SENAITE and authorizes access to the agreed clients and samples. Telematric-managed: request a dedicated hosted installation, review the quote and explicitly accept it before provisioning. Managed activation requires verified HTTPS access and backup, restore and monitoring evidence; it is not instantaneous.

All three arrangements use the same sample/result APIs and support your own dashboard. SENAITE remains responsible for laboratory workflow and publication. Telematric-managed hosting maintains the installation; it does not perform physical laboratory testing or confer accreditation.

Workspace managers can GET/POST /v1/organizations/{org}/water-data/laboratory-arrangement with arrangement (customer_hosted or partner_lab), provider_name, authorization_reference, authorization_confirmed: true and expected_revision. Changed authorization invalidates the previous connection check. Managed mode is assigned by the platform operator after activation.

GET/POST /v1/organizations/{org}/water-data/laboratory-hosting reads or requests hosting. Requests include preferred_region, requirements, request_confirmed: true and expected_revision. POST /laboratory-hosting/actions accepts the current quote with action: accept_quote, quote_accepted: true and its revision, or cancels an unprovisioned request with action: cancel and a reason. These actions do not collect payments or create cloud resources. Installation operations and infrastructure are quoted separately from the water-metering/billing services.

Platform administrators manage requests from Water records → Laboratory connection → Managed lab requests. Mutations require password reauthentication. Endpoint assignment follows a verified connection test; each managed hostname can belong to only one workspace. Customer users cannot overwrite managed credentials or undo operator suspension through connection verification. GET /laboratory-arrangement/events returns the paginated authorization/hosting audit history.

Samples and results

Use /v1/organizations/{org}/water-data/laboratory-samples: GET lists mappings, POST maps an existing sample using sampling_point_id (Telematric), sample_uid, client_uid and sample_point_uid (SENAITE). Read endpoints require water-labs:read; management endpoints require water-labs:manage. Dashboard viewers can read; owners/admins manage.

GET /{id} returns the latest snapshot and freshness; GET /{id}/revisions?limit=25&offset=0 returns immutable history. POST /{id}/sync with an empty JSON object requests synchronization. POST /{id}/status with enabled and expected_revision enables/disables polling. Source sample, client and point UIDs are checked before import. No lab-wide discovery or remote writes occur.

Enabled mappings are polled in bounded batches, at least five minutes between attempts per sample. Published sample values are released only for verified/published analyses whose effective visibility can be confirmed. Unresolved template/profile visibility withholds values. The adapter supports SENAITE 2.6 false/null flags and exact direct-child paths when a read-only account receives empty parent UIDs. Detection-limit qualifiers remain visible even when a formatted result is unavailable. Failed syncs retain history and mark it noncurrent. “Recent” means a successful sync within 24 hours; it does not imply water safety. Previous published values remain in historical revisions after amendments or withdrawal. Only accessible direct analyses are imported; this is not an official complete laboratory report.

Open Water records ↗

Price approved consumption, review charges, and export instructions to your own financial system.

Enable Water billing and Water records. Native Metering, Device cloud and our dashboard are optional. This service is separate from Telematric subscription billing. Your utility supplies its own authorized rates; no rates or automatic billing schedules are seeded.

API access

Base: /v1/organizations/{org}/water-billing. Use a backend X-API-Key with water-billing:read, water-billing:write or water-billing:approve. Device credentials are rejected. Dashboard viewers may read; owners/admins may author and review.

Tariffs

POST /tariffs with source_system, external_id, consecutive version, name, effective_from (UTC), currency (three uppercase letters), minor_unit_exponent (0–3), fixed_charge_minor, allow_estimated (boolean) and tiers. Each progressive tier contains up_to_m3 (decimal string) and rate_minor_per_m3 (integer); the final upper bound must be null. Rates use minor currency units per m³, not major currency units per litre. Tariffs are immutable drafts; POST /tariffs/{id}/review with decision published/rejected and a reason. GET endpoints list versions or retrieve an ID.

Activation times increase by tariff code. The next published activation ends the prior window. A charge period must fit one version. Rates cannot be changed inside a previously approved billing period. Fixed charges apply once per consumption record; they are not monthly-prorated. Estimated consumption requires explicit tariff permission.

Draft charges and review

POST /bills with source_system, external_id, consumption_id, consumption_revision and tariff_id. Consumption must be effectively approved with valid evidence. The response includes a draft utility_charge with a versioned source/rate snapshot, exact minor-unit amount and lines. Integer arithmetic rounds aggregate usage half-up once; largest-remainder allocation makes line amounts equal the total. Taxes, arrears, discounts and credits are not calculated.

POST /bills/{id}/review with expected_version, decision approved/voided and a reason. Only valid drafts can be approved; reviews recheck source and tariff validity. One non-void charge is allowed per consumption identity. Corrections and late evidence flag affected charges for reconciliation rather than silently changing amounts. Explicitly void and replace a charge after reviewing its source. GET /bills and /bills/{id} provide current validation state and immutable calculation details.

Own-dashboard and financial integration

GET /exports?after=0&limit=100 returns ordered events, next_cursor, high_watermark and has_more. Events are water.bill.approved, water.bill.reconciliation_required and water.bill.voided. Persist and deduplicate event IDs, process in cursor order, and drain pages through the high-watermark before finalizing a batch. Continue polling for subsequent changes. The feed is scoped to your workspace; it is not a payment confirmation or signed webhook.

Open the optional utility billing dashboard ↗

Bring your existing metering system and use Telematric through your own dashboard.

Water records & consumption is independent of Device cloud and native Water metering. Shared customers, sites, utility accounts, service connections, zones and sampling points connect future distribution, billing and laboratory integrations. Utility charge calculation is available through the separate Water billing service; SENAITE integration remains planned.

Shared records

Base: /v1/organizations/{org}/water-data. Use a server-side X-API-Key with water:read for GET and water:write for POST. Create or list /customers, /sites, /accounts, /connections, /zones, /sampling-points and /meters. Reuse existing customer/site IDs. Other records require source_system, external_id and name; accounts reference customer_id, connections reference account_id/site_id and optional zone_id, meters reference connection_id/serial_number/installed_at, and sampling points reference site_id with optional zone_id/connection_id. List responses use records (customers/sites retain their existing list keys) and pagination.

Import approved external consumption

POST /water-data/consumptions with water:write and water:approve. Native Metering and Device cloud subscriptions are not required. Send decimal strings in m3 (six decimal places) or L (three); integer millilitre arithmetic preserves precision. The normalized response exposes volume_m3 and original units.

{
  "source_system": "existing-metering",
  "external_id": "connection-42-2026-09",
  "revision": 1,
  "connection_id": "YOUR_CONNECTION_ID",
  "period_start": "2026-09-01T00:00:00Z",
  "period_end": "2026-10-01T00:00:00Z",
  "value": "12345.125",
  "unit": "L",
  "classification": "measured",
  "approval_status": "approved"
}

Review, corrections and export

Use classification: measured|estimated|corrected and approval_status: draft|approved. Estimates, corrections and revisions after 1 require change_reason. Exact source/reference/revision retries return the existing record; conflicting reuse returns 409. New revisions are consecutive and preserve history. Draft corrections leave the prior valid approved revision effective until replacement approval.

GET /water-data/consumptions?view=approved&limit=25&offset=0 exports effective, valid approved records. The latest view includes exceptions; filter either view by connection_id. GET /consumptions/{id}/revisions reads history. POST /consumptions/{id}/review with expected_revision, decision (approved/rejected) and optional reason; rejection requires a reason and both decisions require water:approve. Approved periods cannot overlap for the same connection. Period ends are exclusive; historical imports are supported.

Optional native metering

Enable Water metering plus Water records to POST /v1/organizations/{org}/water-metering/readings using metering:write. Provide meter_id, source_system, external_id, recorded_at, decimal-string value, unit and kind (regular/reset). POST /water-metering/consumptions with opening_reading_id and closing_reading_id plus source/reference/revision to calculate usage. All evidence must be monotonic, from one meter, with no resets or ambiguous timestamps; no more than 10,000 readings per interval. Extra water:approve scope is required for immediate approval. Late evidence flags derived records for reconciliation and removes them from approved exports until resolved through a new revision.

Open the optional water records dashboard ↗

Connect classic ESP32 devices with our Arduino / PlatformIO SDK, version 0.2.0.

Persistent telemetry buffering, command handling, verified firmware downloads and explicit boot health confirmation. Tested on classic ESP32 with espressif32@7.0.1 and ArduinoJson 7.4.3.

Download ESP32 SDK · v0.2.0 SHA-256 checksum

Flash and connect through USB

Our Connect ESP32 wizard handles Wi-Fi, device credentials, the hosted OTA endpoint and HTTPS trust configuration. Use desktop Chrome or Edge with a USB data cable and a classic ESP32 development board with 4 MB flash. Create an active gateway under a customer and site in your workspace first.

Download starter factory firmware · Firmware checksum. Flashing replaces the current firmware and configuration; back up your board first. With esptool installed, flash the merged image at address zero:

python -m esptool --chip esp32 --port PORT write_flash 0x0 telematric-esp32dev-1.8.0-factory.bin

Replace PORT with your USB serial port. Or build and flash the source archive’s examples/GettingStarted with PlatformIO. Close your serial monitor, open the wizard, connect USB, choose the gateway and save Wi-Fi settings. Existing device and OTA credentials are replaced only after your explicit acknowledgement. Setup succeeds only after a new reading reaches the cloud and the board reports healthy to the hosted OTA service. The starter sends diagnostic MCU temperature, changes no GPIO outputs and accepts no actuator commands.

Install and connect

1. Extract the download. Add lib_deps = symlink:///absolute/path/to/TelematricESP32-0.2.0 to your PlatformIO environment. Select the supported ESP32 Arduino platform above.
2. Register a device in Devices and securely provision its device credential. Firmware uses X-Device-Key; workspace API keys stay on your backend.
3. Configure your HTTPS API base ending in /v1, its trusted root CA and device credential. Your application supplies Wi-Fi reconnection and synchronized UTC measurement times.
4. Initialize NVS and DeviceClient, check every return value, enqueue actual measurements, and call device.loop(). See the included README for the C++ example and API contracts.

Buffering and commands

The persistent queue holds eight readings, up to 1,024 JSON bytes each. A full queue rejects new readings without evicting old ones. Retries retain event IDs and original measurement times. Handle rejected records explicitly. Native command polling supports unmapped gateways/sockets with enabled control policy; PowerCell-mapped devices use the backend relay. Command handlers must enforce local interlocks and verify outcomes.

OTA integration

OTA supports PowerCell-compatible collector/socket firmware through Telematric’s hosted HTTPS endpoint. Copy https://app.telematric.com/ota/YOUR_WORKSPACE_ID from Firmware updates and provision only the board-specific OTA token on the device. No customer proxy or workspace API key is needed. Configure a separate HTTPS transport using Authorization: Bearer. Initialize BootGuard and OtaClient, confirm health only after local application diagnostics, and call ota.loop(). Attach device.requireHealthyBoot(guard) when accepting native commands.

A rollback-enabled bootloader and OTA partition layout are required. Two application slots alone do not establish rollback support. Releases require one valid firmware identity marker; see the included README and OTA API reference. Manage compatible releases and deployments in Firmware updates.

Open SDK resources in your dashboard ↗

Connect an Odoo 19/20 installation with JSON-2 API access from Integrations → lims.science. Supply a dedicated read-only API key, database, company ID and the laboratory's actual sample/result model and field mappings. Verification checks permissions and company isolation before records can be browsed. Installation-specific acceptance is required.

Use GET /v1/organizations/{org}/connectors/limsscience/browse/samples or /browse/results, with limit and offset. API keys need connectors:read and water-labs:read. Settings require connectors:manage and water-labs:manage, or a workspace manager session. Read-only responses include source identity and fetched_at; laboratory approval and result changes stay in the LIMS.

Read or save /connection and POST /verify with expected_revision. Saving invalidates verification. Obtain technical mappings from your installation's /doc page or laboratory administrator. No vendor models are assumed.

Configure lims.science ↗

STM32duino / PlatformIO source SDK, version 0.1.0. Reference target: Nucleo F401RE.

Bounded telemetry buffering, command execution journaling and serial provisioning. Hardware tests are pending. Supply a board-specific storage driver and verified network transport.

Download STM32 SDK · v0.1.0 SHA-256 checksum

1. Extract the package and build its offline GettingStarted example using PlatformIO and ArduinoJson 7.4.3.
2. Implement BankStorage over two independently erasable flash or FRAM regions, then initialize JournalStore. MemoryStore is a volatile demonstration tool.
3. Initialize your network peripheral. ArduinoClientTransport requires a CA and a connector that performs TLS chain and hostname verification on the same Client stream.
4. Provision device credentials securely, synchronize UTC time, and enqueue supported measurements.
5. Check storage and API results. Interrupted command execution reports execution_uncertain; confirm actuator outcomes in your application.

Open SDK resources ↗

Available means Telematric offers a functional service that your workspace can subscribe to. It does not grant use. Active means your workspace has subscribed or an administrator has explicitly approved enrollment. Admin approval does not record a payment.

Read GET /v1/organizations/{org}/services. The available flag describes the global catalog; status describes this workspace; access controls use after suspension and dependencies. The subscribed flag identifies verified financial subscriptions. activation_type identifies paid, sandbox or administrator-approved enrollment, and blocked_by lists required services that must be activated.

Sandbox subscriptions are labelled separately and activate development devices while Sandbox mode is selected. Suspended and Unavailable services cannot be used. Coming soon services cannot be activated or purchased. API keys still need the documented scopes.

Use the same requirements and monthly cost breakdown as the Telematric dashboard. Quotes create no checkout or subscription.

GET /v1/organizations/{org}/billing/quote?service_id=environment&gateway=bachs
X-API-Key: YOUR_WORKSPACE_BILLING_READ_KEY

Requires a workspace key with billing:read or an owner/admin account session. Viewer sessions, device credentials and keys from another workspace cannot access the quote. Merchant payments:read is a separate permission. Keep API keys on your backend.

The version-1 response includes rows for the selected service and its deduplicated requirements, blocked_by, ready, totals, additional, incomplete and selected checkout fields. Each row includes its service access/status and a price with amount_minor, currency, mode, provider and source: saved_subscription|checkout_offer. Existing subscriptions use their original rates.

Group amounts by currency and live/sandbox mode. When incomplete is true, show known subtotals rather than a complete total. A null price is not free. Requirements must be active in the same workspace. For example, USD 25 Device cloud plus USD 10 monitoring gives a USD 35 combined monthly rate, with separate subscriptions.

Quotes are nonbinding and expire after five minutes. Refresh on gateway changes and before checkout. Use the selected service’s expected amount/mode, obtain recurring consent and handle server validation errors. Billing-read keys cannot purchase services: checkout and cancellation continue to require an owner/admin session. Each checkout buys one service; losing a requirement does not automatically cancel dependent renewals.

Returns 401/403 for credential or permission errors, 404 for a foreign workspace key, 409 for unavailable checkout offers, 422 for invalid selections and 429 for quotas. Responses are private and uncached. Browse Services →

Workspace owners and administrators can subscribe to Telematric services from Services and manage payments and renewal from Billing. Choose an enabled gateway and review its currency and monthly price: Bachs subscriptions use USD; Paystack uses NGN. Prices are configured separately, with no automatic conversion.

These endpoints require an authenticated account session with owner or administrator access to the workspace. Workspace API keys cannot purchase subscriptions or read billing details. Read checkout_gateways from GET /v1/organizations/{org}/services, then send gateway (bachs or paystack), service_id, accept_recurring: true, expected_amount_minor and expected_mode to POST /v1/organizations/{org}/billing/checkout. Redirect to the returned authorization_url.

On return, send the saved reference to POST /v1/organizations/{org}/billing/verify. The server verifies the provider, workspace, customer, product and paid amount. A browser redirect alone never grants access. GET /v1/organizations/{org}/billing returns subscriptions, pending checkouts and payment history with provider attribution. POST /v1/organizations/{org}/billing/cancel accepts service_id and mode; it stops renewal through the original provider and preserves the verified prepaid period.

Platform administrators configure keys, signing secrets and prices in Administration → Billing, website & security. Secrets stay encrypted on the server. Keep sandbox mode during testing: sandbox transactions activate development devices without requiring admin approval. Bachs webhook endpoint: POST /v1/billing/bachs/webhook. Use Bachs local forwarding for localhost testing. Live and sandbox endpoints require their own signing secrets.

Bachs webhook setup ↗ · Test Bachs webhooks locally ↗

Open Integrations → Software connectors → Connector guide for setup requirements, recorded check results and recovery guidance. Refreshing diagnostics does not contact your source. Run a check or read up to five supported source records explicitly.

GET /v1/organizations/{org}/connectors/{provider}/diagnostics
POST /v1/organizations/{org}/connectors/{provider}/mapping-preview
POST /v1/organizations/{org}/connectors/{provider}/mappings

Requires a workspace manager session, or an API key with connectors:manage and the provider management scope listed in diagnostics. Setup guidance can be read before purchase; checks, source previews and mappings require operational access. Supported profiles: SAP, IBM Maximo, Giswater, SENAITE, Odoo, lims.science and Bachs.

Diagnostics separates configuration revision, access, recorded verification and synchronization evidence. A passed check covers the named operations, not live health or every source permission. Missing synchronization evidence stays unknown. Source settings and credentials remain in the connector settings form.

To preview an identity link, send external_type, external_id, target_type, target_id and expected_connection_revision from diagnostics. Preview checks the current source configuration, target ownership and conflicts without writes or source requests. It does not check that an arbitrary external ID exists.

After explicit confirmation, send the returned proposed fields to /mappings with mapping_confirmed: true and expected_connection_revision. The server rechecks the revision, target and conflicts. On 409, refresh and preview again. Identity links do not import records, translate fields or change your source system.

Start with synthetic data, then enable the capabilities needed by your application.

curl "https://YOUR_TELEMATRIC_HOST/v1/api-key/context" \
  -H "X-API-Key: YOUR_API_KEY"

The right credential for each connection.

Developer keys are returned once on creation or rotation. Keep them on your server. Read and write scopes are separate; rotation preserves the original permissions and expiry. Account sessions cannot replace API keys on forecast endpoints.

Use JSON request bodies with Content-Type: application/json. Use HTTPS in production. Organization and device IDs in paths must belong to the authenticated workspace.

curl "https://YOUR_TELEMATRIC_HOST/v1/api-key/context" \
  -H "X-API-Key: YOUR_API_KEY"

Ship firmware improvements to compatible devices already in the field.

OTA currently supports integrated PowerCell ESP32 collectors (gateways) and sockets using the esp32dev model. Devices need a PowerCell binding, an OTA-capable application image, and an enrolled device credential. Other hardware requires firmware integration.

Management writes require an owner/admin session or an appropriately scoped integration key. Keep management keys on your backend and use HTTPS for device traffic. Manage OTA through the API or the Firmware updates dashboard.

Predictable requests, scoped to your workspace.

Most lists accept limit (default 25, maximum 100) and offset (0–100000). Responses include the collection and pagination with limit, offset, and total.

Default developer-key limits are 60 requests per minute per key and 10,000 requests per organization per UTC calendar month. Deployment settings can change these values. Check the Usage page for your current allowance.

Accepted key authentication reserves one request, including cached responses and subsequent validation/provider failures. Invalid credentials and scope denials do not consume developer quota. Rotating a key does not reset usage.

Use HTTP status codes to decide what your integration does next.

{
  "status": "error",
  "message": "Invalid request."
}

Export retained fleet records, native telemetry, water records, selected laboratory/GIS revision history and connector identity links as bounded JSON pages. Use an owner/admin session or a dedicated backend key with exports:read. This grants bulk access to all manifest categories, including customer contact information and retained laboratory results. No paid service activation is required; ordinary request limits still apply.

GET /v1/organizations/{org}/exports
GET /v1/organizations/{org}/exports/telemetry?limit=100

The manifest lists fields, units and exclusions. Save each page and repeat the same category/limit with URL-encoded cursor=next_cursor. Stop at complete: true and a null cursor. Most categories allow up to 100 records and 256 KiB of record data. Laboratory revisions and GIS snapshots allow up to 10 records and 1 MiB. Read category-specific limits and record keys from the manifest; envelope overhead is additional. Tokens expire after 24 hours; authorization is checked on every page. A token alone does not grant access. Deduplicate by the manifest record key when retrying or restarting; consumption and laboratory histories use parent ID plus numeric revision.

Exports are bounded live reads: later arrivals are excluded by an initial server cutoff, while updates/deletions can change subsequent or replayed pages. Telemetry eligibility uses server receipt time; original device timestamps and metric values are preserved. Categories do not share an immutable snapshot. Credentials, configuration secrets and raw audits are excluded.

This initial version is not a complete workspace archive. Water exports preserve original units, source IDs, approval states and all retained consumption revisions. Selected SENAITE result histories preserve precision and publication flags; GIS snapshot histories retain stored CRS and geometry. Source references join through the parent categories. These exports do not fetch live lims.science/source inventories or establish current laboratory approval. Billing, model artifacts and other manifest exclusions remain accessible through supported read APIs or support-assisted export. CSV and wider archive coverage remain planned. Export does not cancel subscriptions or delete data. Ask support@telematric.com for a consistent archive or assistance with request limits.

In Connector guide → Disconnect & retained data, managers can disconnect supported software connectors and forget their saved credentials. History and subscriptions remain separate. No paid activation is required to disconnect.

POST /v1/organizations/{org}/connectors/{provider}/disconnect
{"expected_revision":3,"disconnect_confirmed":true}

Use a manager session or connectors:manage plus the provider management scope. Disconnect increments the configuration revision, clears saved credentials and verification, and releases the allocation. Reconnect requires new credentials and verification; managed labs need the platform team. Already-dispatched requests may finish. Revoke credentials at the vendor for source-side revocation. This does not cancel renewal, stop hosted laboratory infrastructure or affect Telematric’s separate billing gateway.

Workspace owners can preview and permanently delete selected local GIS records with snapshot history, selected SENAITE samples with result history, or identity links. The relevant source must be disconnected first and active synchronization leases must finish. Export first if needed. These actions do not delete source-system records, water installations, subscriptions or unrelated identity links.

POST /v1/organizations/{org}/data-deletions/preview
{"category":"gis_records","record_ids":["YOUR_RECORD_UUID"]}

POST /v1/organizations/{org}/data-deletions/confirm
{"confirmation_token":"YOUR_PREVIEW_TOKEN","delete_confirmed":true,"current_password":"YOUR_CURRENT_PASSWORD"}

GET /v1/organizations/{org}/data-deletions

Deletion requires the owner account session and current password; API keys and administrator/member/viewer sessions cannot authorize it. Preview accepts 1–20 UUIDs and at most 1,000 history rows. Its token expires in ten minutes and binds the owner, workspace, selected records and connector revisions. Changed selections, reconnections and active leases require a fresh preview. Confirmation is transactional; retries return the same receipt. The history endpoint returns the owner’s latest 100 receipts.

Native telemetry and operational history are stored by Telematric. SAP/Maximo reads are bounded source requests; selected GIS and laboratory records may be retained as snapshots. APIs return the supported records, not a promise of a complete source-system mirror.

Use workspace-scoped APIs and keep source IDs, units, timestamps and provenance in your application. AI training requires explicit workspace/service authorization; disabling it is different from deleting original telemetry.

Stopping renewal, disconnecting a source, revoking a key and deleting retained records are separate actions. Complete workspace archives and erasure beyond the selected local categories remain support-assisted: hello@telematric.com. Do not assume that cancellation erases data, that a backup is an export, or that expiry immediately deletes every stored copy.

Resumable JSON export for the documented retained-data categories is available above; broader archive coverage and retention automation remain roadmap work. Check effective API limits in Usage and platform pricing. Current data-handling controls are described in our privacy policy and terms.