Machines API

Base path: /v1/organizations/:organization_id/machines

Endpoints

Method	Path	Description
GET	/machines	List all machines
GET	/machines/:id	Get a machine
POST	/machines	Create a machine
PATCH	/machines/:id	Update a machine
DELETE	/machines/:id	Delete a machine
GET	/machines/search	Search by designation
GET	/machines/:id/tool_crib	Get tools currently at a machine

Machine object

{
  "id": 1,
  "name": "DMG 5-axis",
  "designation": "DMG-001",
  "builder": "DMG Mori",
  "model": "DMU 50",
  "serial_number": "SN123456",
  "hour_rate": 120.0,
  "target_oee": 85,
  "created_at": "2025-01-15T08:00:00Z",
  "updated_at": "2025-06-01T10:00:00Z",
  "warehouse_access_point": { "id": 3, "name": "CNC Area" },
  "created_by": { "id": 7, "email": "user@example.com" },
  "components": [
    {
      "id": 44,
      "component_type": "spindle",
      "name": "Main Spindle",
      "interfaces": [{ "code": "HSK01C0630****" }],
      "data": {},
      "tool_crib": false
    }
  ]
}

Parameters

Create / update

Parameter	Type	Description
name	string	Display name
designation	string	Machine code. Always pass this explicitly.
builder	string	Manufacturer name
model	string	Machine model
serial_number	string	Serial number
hour_rate	decimal	Cost per operating hour
target_oee	decimal	Target OEE (0–100)
warehouse_access_point_id	integer	WAP the machine belongs to. If omitted, defaults to the first WAP in the organization.
organization_id	integer	Required in the request body on create, not just in the URL. The :organization_id path segment authorizes the request but does not by itself associate the new machine with that organization — pass it again in the body.
user_id	integer	Associates the record with a specific user for role-based scoping (see Authentication). Leave unset unless you know you need it.

Like Parts, Machines auto-generate designation from an organization sequence when left blank — number is an alias for designation on the Machine model, so the same blank-designation handling that works for Parts works here too.

Search

Parameter	Type	Description
designation	string	Exact match on machine designation

Examples

# List all machines
curl "https://api.toolingmetrics.com/v1/organizations/12/machines" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Find a machine by designation
curl "https://api.toolingmetrics.com/v1/organizations/12/machines/search?designation=DMG-001" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get the live tool crib for a machine
curl "https://api.toolingmetrics.com/v1/organizations/12/machines/1/tool_crib" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create a machine — organization_id is required in the body, not just the URL
curl -X POST "https://api.toolingmetrics.com/v1/organizations/12/machines" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mazak 3-axis", "designation": "MAZ-002", "builder": "Mazak", "model": "VCN-430A", "organization_id": 12}'

import requests

BASE = "https://api.toolingmetrics.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_TOKEN"}

# Check which tools are loaded at a machine before a setup
crib = requests.get(
    f"{BASE}/organizations/12/machines/1/tool_crib",
    headers=HEADERS,
).json()

for assembly_id, tools in crib.items():
    for tool in tools:
        remaining = [edge["remain_life_percentage"] for edge in tool["cutting_edges"] if edge["remain_life_percentage"] is not None]
        print(f"  T{tool['number']} — {tool['name']} — remaining {min(remaining) if remaining else 0}%")

Tool crib

GET /machines/:id/tool_crib returns tools currently stored at the machine, grouped by tool assembly ID. Each entry is filtered down to a fixed set of fields — note that id is not one of them:

{
  "42": [
    {
      "number": "T-001",
      "name": "Face Mill Ø80",
      "status": "active",
      "completed": true,
      "updated_at": "2025-06-01T08:00:00Z",
      "weight": 1.8,
      "usage_at": "2026-05-30T14:00:00Z",
      "cutting_edges": [
        {
          "id": 12,
          "item_id": 84,
          "condition": "used",
          "usage_life": 4.5,
          "life_limit": 20.0,
          "remain_life_percentage": 77.5,
          "completed": true
        }
      ],
      "component_id": 44,
      "slot_number": 3
    }
  ]
}

Keys are tool assembly IDs (integers as strings). Each value is an array of tool records sorted by the limiting cutting edge’s remain_life_percentage descending. Tools without a cutting edge life limit are listed last.

Field	Description
number	Tool number assigned at assembly station
name	Tool name
status	Current status
completed	Whether all assembly components are present
weight	Tool weight
usage_at	Timestamp of last usage record
cutting_edges	All cutting edges and their current index, condition, usage, life limit, life unit, remaining-life percentage, completion, quantity, and CRP data
component_id	Which machine component (head/turret/gang, from components in the machine object) the tool is loaded into. Only present if the tool has been assigned a crib slot — a tool physically at the machine but not yet slotted into a component omits this and slot_number entirely
slot_number	Pocket/position number within that component (lathe turret position, or magazine slot)

slot_number is not validated against the component’s own pocket definitions. A machine component separately defines its physical pockets as Machine Tool Location records (each with its own slot_number, unique per component — that’s what the components array in the Machine Object above represents). The slot_number returned here comes from a second, independent occupancy map (tool_crib) that is only kept in sync with those pocket definitions by convention — matching integers, not a foreign key. Don’t assume a tool_crib entry’s slot_number necessarily corresponds to an existing, currently-defined pocket on that component; treat it as “the number recorded when this tool was last slotted,” not a validated reference.

Related articles

• Organizations API
• Tool assemblies API
• Parts API
• Projects API