The API

The API is for the moment a quoting tool wants the throughput and payback of a study without someone copying numbers out of a report, or a fleet manager wants to send daily run data in without a spreadsheet. It is available on Team and Enterprise, on auddomate.com and on self-hosted installations alike. Everything it returns is what you see in the app: the same fleet, the same assumptions, the same arithmetic.

#Keys

Owners create keys under Settings → API keys. Name each one for the system that will use it, tick what it may do, and copy the key when it appears — it is shown once and stored hashed. A key has one or more scopes:

read

Studies, results, machines and the catalogue. Every key has this.

telemetry

Write telemetry rows to a study.

audit

Read the audit log.

Revoke a key from the same page; anything still using it gets 401 from that moment. Creating and revoking keys is itself written to the audit log. Up to twenty live keys per organisation.

#Calling it

Every request carries the key as a bearer token. The base address is your Auddomate address followed by /api/v1.

curl -H "Authorization: Bearer aud_…" https://auddomate.com/api/v1/me

If something between you and the server strips the Authorization header, send it as X-Api-Key: aud_… instead. Responses are JSON with a stable shape:

{ "ok": true, "data": …, "meta": { "page": 1, "per_page": 50, "total": 132, "pages": 3 } }
{ "ok": false, "error": "not_found", "message": "No study ST-9999 in this organisation." }

Lists page with ?page= and ?per_page= (up to 200). Times are the server's local time in YYYY-MM-DD HH:MM:SS; lengths are millimetres, distances metres, rates per hour or per day, exactly as in the app. Each key may make 300 requests a minute; beyond that you get 429 with a Retry-After header.

#Endpoints

GET /api/v1/me

The organisation, the key's name and scopes, the edition and the rate limit. Use it to check a key works.

GET /api/v1/studies

Every study: ref, name, site, client, status, the current scenario's throughput verdict and headroom, and the number of units on its fleet. Filter with ?status=, ?client= or ?updated_since=2026-09-01.

GET /api/v1/studies/{ref}

One study in full, by reference (ST-1001) or id: the plan (file, scale, extent, how many racks, aisles, docks and obstructions), and every scenario with its fleet lines, assumptions, throughput result line by line, the aisle check against the most demanding machine, and which machine that was.

GET /api/v1/studies/{ref}/telemetry

The run data on a study, one row per machine per day.

GET /api/v1/studies/{ref}/pdf

The report as a PDF file, made on the server. ?lang= and ?units=imperial choose language and units. /versions/{n}/pdf for a saved version.

GET /api/v1/studies/{ref}/versions

The saved versions of a study, newest first; /versions/{n} returns one in full in the same shape as the study itself, and ?diff=1 adds what has changed since.

POST /api/v1/studies/{ref}/telemetry

Write run data. Needs the telemetry scope. Send {"rows": [...]}, up to 5 000 rows; each row names the machine by machine_id or machine (its exact name), a day, and any of moves, run_minutes, idle_minutes, distance_km, faults. A row for a machine and day that already exists is replaced. The reply says how many were written and lists the first fifty rows that were skipped and why.

GET /api/v1/machines

Your machine library, every profile with its figures and, for catalogue models, the datasheet it came from. /machines/{id} for one.

GET /api/v1/catalogue

The catalogue of real makes and models with their source datasheets. Filter with ?vendor= or ?class=.

GET /api/v1/audit

The audit log, newest first. Needs the audit scope. Filter with ?group=, ?from=, ?to=, ?q=.

#What a study looks like

{
  "ref": "ST-1002", "name": "Cold store aisle audit", "status": "review",
  "plan": { "file": "cold-store.dxf", "scale": { "mm_per_unit": 1, "source": "dxf" },
            "extent_mm": { "width": 61000, "height": 45000 },
            "shapes": { "rack": 6, "aisle": 5, "dock": 1, "block": 3 } },
  "scenarios": [ {
    "name": "Base", "current": true,
    "fleet": [ { "machine": "VNA turret, 1.0 t", "class": "vna", "qty": 3, "shifts": 2 } ],
    "assumptions": { "moves_required": 2110, "hours_per_shift": 8, "days_per_year": 300,
                     "distance_m": 14, "distance_source": "plan", "handling_s": 55 },
    "throughput": { "verdict": "meets", "moves_per_day": 3024.6, "required_per_day": 2110,
                    "headroom_per_day": 914.6, "utilisation_pct": 69.8, "lines": [ … ] },
    "aisles": { "verdict": "fail", "aisle_min_mm": 2100, "narrowest_mm": 1800, "aisles": 5, "below": 5 },
    "checked_against": { "machine": "Pallet truck, pedestrian 1.6 t", "aisle_min_mm": 2100 }
  } ]
}

throughput.verdict is one of meets, short, nofleet, nodistance or notarget; aisles.verdict one of pass, fail, noplan, noscale, noaisles or none. distance_source says whether the travel distance was typed in or derived from the plan, as the Simulation page does.

#Sending run data

curl -X POST https://auddomate.com/api/v1/studies/ST-1002/telemetry \
  -H "Authorization: Bearer aud_…" -H "Content-Type: application/json" \
  -d '{"rows": [
        {"machine": "VNA turret, 1.0 t", "day": "2026-09-01", "moves": 412, "run_minutes": 480, "idle_minutes": 60, "distance_km": 18.4, "faults": 1},
        {"machine_id": 327, "day": "2026-09-02", "moves": 390}
      ]}'

{ "ok": true, "data": { "written": 2, "skipped": 0, "errors": [] } }

#Errors

401 unauthorised

No key, or one we do not recognise.

401 revoked

The key was revoked; the message says when.

403 plan

The organisation is on Free or Studio.

403 scope

The key lacks the scope the endpoint needs.

404 not_found

No such study, machine or endpoint.

400 json / empty

The body was not a JSON object, or had no rows.

413 too_many

More than 5 000 rows in one telemetry request.

429 rate_limited

Over 300 requests in a minute. Wait for Retry-After seconds.

#Versioning

The path carries the version. Fields are added to v1 over time but never renamed or removed; anything that would break a client becomes v2, with v1 kept running alongside for at least a year. Changes are listed in the changelog like everything else.