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.

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

Status	Meaning	Typical Fix
200	Success	—
401	Missing/invalid token	Ensure header format is `Authorization: Bearer …` and token is current
403	Insufficient permissions	Verify token scope or rotate a new token with required access
429	Rate limited	Back off and retry with exponential delay

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.

Loading…

1Pick a language

2Try It!