Getting Started with the TelemetryOS API

Welcome to the TelemetryOS API. This guide is a short, practical orientation for developers who want to automate deployments, manage devices, and power data‑driven screen experiences. You’ll authenticate with a bearer token, call a simple endpoint to confirm access, then see concise code samples you can adapt to your stack.

Overview

The TelemetryOS API exposes the same control plane used by the dashboard. You can enroll and manage devices, publish media and applications, schedule content, and retrieve logs and analytics. Most workflows follow a simple pattern: authenticate with a token, call a REST endpoint over HTTPS, and handle a JSON response that includes data and optional pagination.

What you need

A TelemetryOS account at app.telemetryos.com and an API token generated from Settings → API Tokens. Treat the token like a password; store it securely and rotate if compromised.

Authentication

Authentication uses a bearer token sent with each request. After generating a token in the dashboard, include it in the Authorization header exactly as shown below. No other headers are required beyond standard JSON content types.

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

If the token is valid, the API responds with 2xx status codes; invalid or expired tokens return 401/403 with a short error body.

Your First Request

A quick way to verify access is to list devices associated with your account. The example below uses cURL and returns a standard paginated JSON payload.

curl -X GET "https://api.telemetryos.com/v1/devices" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Typical responses include a top‑level data array and a pagination block:

{
  "data": [
    {
      "id": "device-123",
      "name": "Lobby Screen",
      "status": "online",
      "lastSeen": "2025-09-26T12:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 1 }
}

Code Examples

JavaScript (Node.js) with axios provides a clear template for authenticated requests and basic error handling:

const axios = require('axios');

const API_TOKEN = process.env.TX_API_TOKEN;
const BASE_URL = 'https://api.telemetryos.com/v1';

async function getDevices() {
  try {
    const res = await axios.get(`${BASE_URL}/devices`, {
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    });
    console.log(res.data);
  } catch (err) {
    const status = err.response?.status;
    const message = err.response?.data || err.message;
    console.error(`Request failed (${status}):`, message);
  }
}

getDevices();

Python with requests follows the same pattern:

import os, requests

API_TOKEN = os.getenv('TX_API_TOKEN')
BASE_URL = 'https://api.telemetryos.com/v1'

headers = { 'Authorization': f'Bearer {API_TOKEN}', 'Content-Type': 'application/json' }

resp = requests.get(f'{BASE_URL}/devices', headers=headers)
if resp.ok:
    print(resp.json())
else:
    print(f'Error {resp.status_code}: {resp.text}')

Common Responses

Next Steps

Browse the API reference to discover available resources and parameters, then automate end‑to‑end flows like provisioning, publishing, and monitoring. For practical integration details, review the Authentication and SDK guides:

• Authentication: see authentication.md
• SDK Integration for on‑screen apps: see sdk-integration.md

If you prefer to explore interactively, start from the dashboard’s API token page and use the token with the cURL example above. Once you can list devices, you’re ready to create content, schedule playlists, and ship changes through CI to your fleet.