How access works

TopXView uses HTTP Basic Auth: a username + password ride along (HTTPS-encrypted) with every request. Basic Auth is the only supported method — there are no API keys. Without credentials the server answers 401 Unauthorized; that's how you know auth (not the network) is your problem.

Accounts are self-managed in the topXview GUI (add / modify / delete). Permissions are all-or-nothing: an API user sees everything the API exposes. Every access is logged server-side (T:\RestAPILogs, by date).

Using your credentials in your own tools

# curl — the -u flag is Basic Auth
curl -s "https://ads.restapi.telegra-inc.com:9081/txvapi/history/getHistoryData" \
  -u "adsdotapiuser:$PASSWORD"

# Python
requests.get(url, auth=HTTPBasicAuth("adsdotapiuser", password))

# Postman: Authorization tab -> Type: Basic Auth -> fill username + password

Quick triage: 401 = wrong or missing credentials · timeout = you're calling the old deprecated http://…:8080/:9080 endpoints (IP-allowlisted) — switch to https://ads.restapi.telegra-inc.com:8081/:9081. TopXView accepts Basic Auth only.

System architecture

The one-sentence version

It's like a research desk at an archive: you hand over a slip saying what you want and which dates, the clerk fetches the matching records, and hands you back a neat stack.

Watch a request happen

Press the button. A request travels from your computer to the TopXView server, and the data comes back.

1. You fill out and send a request.
2. It travels over the network to the server.
3. The server looks up the matching records.
4. The data comes back to your computer.
5. The portal shows it to you. Done!

Anatomy of a request

A request is just a short form written in JSON — a simple text format of "label": value pairs. Click any highlighted part below to see what it means in plain English.

{
  "DataType": "MotionData",
  "FilterFlags": 0,
  "EventFilterList": [],
  "TimeFilter": {
    "StartTime": "2025-11-08T18:00:00Z",
    "EndTime":   "2025-11-08T18:05:00Z"
  },
  "PagingRequest": { "PageSize": 50000, "PageIndex": 1 }
}

Good news: only one field really changes from one question to the next — DataType. Everything else stays almost the same. Learn this shape once and you can ask for any of the seven data elements.

What comes back — the response envelope

getHistoryData does not return a bare list. It wraps records so you can check for errors and paginate. Every client follows the same rule.

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "Response": [ /* records here */ ],
  "Page": { "PageIndex":1, "PageSize":50000, "TotalPages":3 }
}

Why this matters: the 200,000-record limit

The server will not hand back more than 200,000 records in a single answer — a safety limit so no one request can overwhelm it. A few minutes of object data can blow past that easily. There are two complementary ways to get everything anyway:

Ready. Each cell is one request for one page.

The paging loop

Increment PageIndex (1-based on the production HTTPS server — PageIndex 0 returns an "OFFSET may not be negative" error) and stop when PageIndex ≥ Page.TotalPages, or when a page comes back empty.

Rules of thumb: PageSize 50,000 max · chunk very large windows by day/week · MotionDetectionData (objects) is the heaviest element — page in seconds, not minutes.

How the video is stored

Each camera saves video one frame at a time. Every frame is a tiny file ending in .bin — a single VP9-compressed image (~720×464) plus a small label: its order, its size, and whether it's a full "key" frame. Frames arrive about 10 times a second. Roughly every 5 minutes of frames are zipped together and attached to an event.

The names tell you everything — which vehicle, which camera, and the exact start/end time (in microseconds since 1970). Camera positions per Telegra: FL/FC/FR front left/center/right, LC left center, RC rear center, BC back center. (RC = "rear" alongside BC = "back" is Telegra's wording — if the distinction matters for your pull, confirm with them; earlier notes read RC as right-center.)

# the zip of ~5 minutes of frames
<chid>_<cam>_<start_us>_<end_us>.zip
# one frame inside it
<chid>_<cam>_<frame_us>.bin
# 1 · find the event: ReferenceId prefix = project (P2_… May, P3_… Nissan)
https://ads.restapi.telegra-inc.com:8081/txvapi/status/getActiveEvents?select=EventId,StartTime,EndTime,ReferenceId
# 2 · list every zip attached to that event (returns ready-to-use paths)
https://ads.restapi.telegra-inc.com:8081/txvapi/status/getActiveEvents?eventId=<eventId>&select=Attachments
# 3 · download each one by its listed path
https://ads.restapi.telegra-inc.com:8081/evman/events/attachments/0/0/<eventId>/<zip>

What the extractor does

Build your extraction command

Fill these in and copy the ready-to-run command. (This builds the command — running it needs the prerequisites below and a network path to the host.)

This exact configuration was run end-to-end on 2026-07-13 (vehicle 19201, FC camera, event 215, 23:10–23:12 UTC spanning two zips): downloaded over HTTPS, decoded, stitched across the zip boundary and trimmed to a frame-accurate 2:00 MP4 — 720×464, 10 fps, 1,200 frames — showing the van's front camera on the highway. Note: if your start time is before the first zip's first frame, the video simply starts at the footage's beginning.

Ready-to-run command

Resolved attachment URLs

Prerequisites

# ffmpeg (system) + Python packages
winget install ffmpeg            # Windows  (apt/brew on Linux/macOS)
pip install requests protobuf==3.20.3 pytz

# frame decoding: a verified pure-Python image_t shim ships with this repo
# (scripts/may/tele_op/types/) — no PYTHONPATH setup needed. To use May's
# official module instead, put ads_dashboards/data on PYTHONPATH first.

# auth + endpoint are read from .env automatically (TXV_USER / TXV_PASS)

Simpler alternative: recorded AVI

If you don't specifically need the raw onboard frames, TopXView can serve recorded camera video directly as an AVI — no zips, no protobuf, no VP9 decode. Fewest moving parts.

https://ads.restapi.telegra-inc.com:8081/txvapi2/TxvApi/getStreamRecordingAvi?streamChid=<videoChid>&utcTimeStart=<unixSeconds>&length=<seconds>&flags=0

Two caveats: it keys on a video-stream Chid (different from the 192xx data Chid), and the source files live on the file system (T:\tXv_Video), not the database. Confirm host/port and the stream-Chid mapping with Telegra first.

Good to know

• ~720×464 at 10 fps. A ~12 MB zip in ≈ ~33 MB MP4 out for ~5 minutes.
• Seams may stutter — frames can drop between zips, so don't treat the MP4 as frame-accurate for timing.
• Heavy compression — plates and faces are mostly unreadable.
• Confirm the vehicle was running first (a quick MotionData pull) to avoid a wasted extraction.

Resolved 2026-07-13: the attachment-listing endpoint (getActiveEvents?eventId=<id>&select=Attachments) and the auth transport (HTTP Basic) are both verified working. Still open with Telegra: the stream-Chid map for the AVI path.

pip install requests
python scripts/verify_access.py
# known-good window (8/8 PASS on 2026-07-13):
python scripts/verify_access.py --page-size 1000 \
    --start 2025-02-05T20:00:00Z --end 2025-02-05T20:10:00Z

What a passing run looks like

Illustrative — real counts come from your run. EMPTY (200 but no rows in the window) is not a failure.