FillTrax API Reference

How tire-fill machines (or the gateways beside them) send every fill cycle to FillTrax over HTTPS.

Overview

FillTrax records one reading per fill cycle: when it finished, who ran it, how much was filled, how long the pump ran, and optionally the target weight and fill mix. Everything in FillTrax (live status, Insights, reports, alerts, the assistant) is built from these readings.

The API is a small, write-only ingestion API: a machine authenticates with its own API key and posts readings as JSON. There are two ways to send them: one reading per request as each cycle finishes, or several at once in a batch (for example after a connection outage).

What the API can do

• Record fill cycles for one machine per API key, live as they happen.
• Send buffered cycles in batches of up to 500, e.g. after the machine was offline. Each reading in a batch stands on its own.
• Validate every reading on arrival, and say exactly what's wrong with any it rejects.
• Ignore repeats safely: a reading with a sequenceId FillTrax already has is skipped, so retries never double-count.
• Check in without data: an empty batch tells FillTrax the sender is alive (it updates the machine's "last seen").
• Accept timestamps from any timezone, as long as the offset is included.
• Keep extra fields you send for debugging, without letting them affect any numbers.

Getting started

1. In FillTrax, add the machine (Machines → Add machine) and allocate a license to it (an owner can do this from the machine's page or Licenses).
2. Copy the API key shown when the license is allocated. It starts with ftk_live_ and is shown once: FillTrax stores only a hash and can't show it again.
3. Configure the machine or gateway to POST each cycle to /api/ingest/telemetry with the key (below).
4. Send a test reading. Within seconds it appears on the machine's page under Recent telemetry, and the HTTP API source shows "Receiving data".

Authentication

Every request carries the machine's API key as a bearer token:

Authorization: Bearer ftk_live_xxxxxxxxxxxxxxxxxxxxxxxx

The key identifies the machine, so readings never name a machine themselves. A request is accepted only if:

• the key is valid and its license is still allocated to a machine,
• the machine's status is active, and
• its HTTP API data source isn't paused, and the customer's account isn't cancelled.

Removing a machine's license, deactivating the machine or pausing its data source stops data immediately, without any change on the machine. Always use HTTPS.

Endpoints

Request bodies are JSON with Content-Type: application/json; responses are JSON.

The reading object

One fill cycle. Unknown fields are ignored for all metrics (but kept with the raw reading, for debugging).

{
  "recordedAt": "2026-09-27T14:25:59Z",
  "operatorId": "12",
  "fillWeight": 51,
  "cycleTimeMs": 128000,
  "targetWeight": 50,
  "liquidRatio": 0.98,
  "grindRatio": 0.02,
  "sequenceId": "SN1234-000418"
}

Send one reading

The body is a single reading object. Send it when the cycle finishes.

Send a batch

The body is a JSON array of up to 500 readings. Use it to flush cycles buffered while offline, or to upload a run of cycles at once. Each reading is checked and stored on its own: good ones are recorded even when others in the same batch are rejected.

[
  { "recordedAt": "2026-09-27T14:25:59Z", "operatorId": "12", "fillWeight": 51, "cycleTimeMs": 128000, "sequenceId": "SN1234-000418" },
  { "recordedAt": "2026-09-27T14:32:21Z", "operatorId": "12", "fillWeight": 49, "cycleTimeMs": 124500, "sequenceId": "SN1234-000419" }
]

Checking in: an empty array [] returns 201 with "count":0 and records nothing, but updates the machine's "last seen". Useful for a sender that only has data now and then.

Resending a whole batch after fixing a rejected reading is safe as long as the readings carry sequenceIds: the ones already recorded come back as duplicates.

Health check

Returns 200 {"status":"ok"} when FillTrax is up. No authentication. Handy for a gateway to test connectivity before sending.

Status codes & errors

Recommended sender behavior: on 2xx, discard the reading; on 400, log it and discard (it will never be accepted as is); on 401/403, stop and alert someone; on 5xx or a timeout, keep it and retry.

Duplicates & retries

Give every reading a sequenceId that's unique to that cycle and stays the same if you send it again. FillTrax skips any reading whose sequenceId it already has, so a retry after a timeout, a resent batch, or a replay of a buffered log never counts a tire twice.

• Readings without a sequenceId are always stored, so a retried one would be counted twice.
• A rejected reading's sequenceId is not remembered, so you can fix the reading and resend it under the same ID.

Times & timezones

• recordedAt must include its offset (Z for UTC, or e.g. -07:00). A bare local time is rejected, because FillTrax would otherwise have to guess the machine's timezone.
• Readings up to 5 minutes in the future are accepted (clocks drift); later ones are rejected with recordedAt is in the future; check the machine's clock. Keep the machine's clock synced (NTP).
• Old readings are fine: a batch of last week's cycles is recorded with their real times and shows up in that week's reports.
• FillTrax shows each time in the viewing user's own timezone, and works out days and shifts in each location's timezone.

Code examples

curl -X POST https://dashboard.filltrax.com/api/ingest/telemetry \
  -H "Authorization: Bearer $FILLTRAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recordedAt": "2026-09-27T14:25:59Z",
    "operatorId": "12",
    "fillWeight": 51,
    "cycleTimeMs": 128000,
    "targetWeight": 50,
    "sequenceId": "SN1234-000418"
  }'

import os, requests
from datetime import datetime, timezone

reading = {
    "recordedAt": datetime.now(timezone.utc).isoformat(),
    "operatorId": "12",
    "fillWeight": 51,
    "cycleTimeMs": 128000,
    "targetWeight": 50,
    "sequenceId": "SN1234-000418",
}
r = requests.post(
    "https://dashboard.filltrax.com/api/ingest/telemetry",
    json=reading,
    headers={"Authorization": f"Bearer {os.environ['FILLTRAX_KEY']}"},
    timeout=30,
)
if r.status_code in (200, 201):
    pass                      # recorded (or already recorded)
elif r.status_code == 400:
    print("rejected:", r.json().get("details"))   # fix, don't retry as is
elif r.status_code in (401, 403):
    raise SystemExit(r.json()["error"])           # key or machine problem
else:
    ...                       # 5xx: keep the reading and retry later

const res = await fetch("https://dashboard.filltrax.com/api/ingest/telemetry", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FILLTRAX_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    recordedAt: new Date().toISOString(),
    operatorId: "12",
    fillWeight: 51,
    cycleTimeMs: 128000,
    targetWeight: 50,
    sequenceId: "SN1234-000418"
  })
});
const body = await res.json();
if (!res.ok) console.error(res.status, body.error, body.details ?? "");

$headers = @{ Authorization = "Bearer $env:FILLTRAX_KEY" }
$reading = @{
  recordedAt  = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
  operatorId  = "12"
  fillWeight  = 51
  cycleTimeMs = 128000
  targetWeight = 50
  sequenceId  = "SN1234-000418"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "https://dashboard.filltrax.com/api/ingest/telemetry" `
  -Headers $headers -ContentType "application/json" -Body $reading

curl -X POST https://dashboard.filltrax.com/api/ingest/telemetry/batch \
  -H "Authorization: Bearer $FILLTRAX_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"recordedAt":"2026-09-27T14:25:59Z","operatorId":"12","fillWeight":51,"cycleTimeMs":128000,"sequenceId":"SN1234-000418"},
    {"recordedAt":"2026-09-27T14:32:21Z","operatorId":"12","fillWeight":49,"cycleTimeMs":124500,"sequenceId":"SN1234-000419"}
  ]'

What happens to the data

• Live: open FillTrax pages update within seconds of a reading arriving: the Overview's machine status (running, idle, stopped), today's tires, pump rate and cycles per hour.
• Metrics: pump rate (fillWeight ÷ cycleTimeMs) against the machine's rated maximum, utilization, stops, operator pace, and, when targetWeight is sent, on-target fills and over-fill giveaway.
• Reports & alerts: daily reports (PDF and CSV), Insights over 24 hours to 90 days, and alerts for a machine that stops mid-shift, goes quiet, runs slow or sends rejected readings.
• Rejected readings are kept with the reason and shown on the machine's page under Data sources ("Failed to parse"), so whoever maintains the integration can see what's wrong without server access.

Without code: CSV options

For machines that write CSV logs instead of calling an API, FillTrax has three no-code routes. They all read the same columns and use the same duplicate protection, so a row is never counted twice whichever way it arrives.

Columns are recognized from the header row; the controller's usual log layout works as is:

Date,Time,Mach ID,Tire ID,Oper ID,Tire Fill,Target Wt,Liq %,Fill Time
9/27/2026,14:25:59,1,418,12,51,50,98,2.13

CSV times have no timezone, so they're read in the machine location's timezone set in FillTrax.

Limits at a glance

What it doesn't do

• No reading data back. The API only receives. Reports, CSV exports and PDFs are downloaded from the FillTrax dashboard by signed-in users.
• No editing or deleting readings through the API. (CSV imports can be undone from the dashboard.)
• No managing machines, users or licenses through the API; that's done in the dashboard.
• No webhooks or push notifications to outside systems; alerts go to FillTrax users by email and in the app.

Troubleshooting