Concepts

Organization scoping, request/response shape, date formats, file attachments, and what's not yet available.

Updated October 29, 2026

Base URL

The API is served from its own subdomain, not a path under the main app:

https://api.toolingmetrics.com/v1

All requests and responses use JSON. Set Content-Type: application/json on write requests.

Organization scoping

Every resource in Tooling Metrics belongs to an organization. Most endpoints require an organization_id path segment:

GET /v1/organizations/:organization_id/machines
GET /v1/organizations/:organization_id/parts

Retrieve your organization ID from GET /v1/organizations. An organization_id that doesn’t exist answers 401 Unauthorized, with the same body as an organization your token cannot reach, so the API doesn’t tell which organization IDs exist. A record is looked up only in the organization the URL names: a record of another organization answers 404 Not Found, with the same body as an id that doesn’t exist, even when your token may read it under its own organization’s ID.

Passing a valid organization_id you belong to isn’t the whole story — your role for that specific resource type further limits which records you can see. See the “Authorization Scoping” section in Authentication.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Tokens are personal — generated and revoked on the API Tokens tab of your account settings (avatar → Setting), not in an organization admin area. Each token carries the same access as the user who created it. See Authentication.

No pagination

List endpoints (index, search) are not paginated — they return every matching record in a single response. There is no page or per_page parameter. If your organization has a very large number of records of a given type, plan for a potentially large response body; filter with the resource-specific query parameters documented in each reference page instead of relying on pages.

List responses are bare JSON arrays — no envelope wrapper:

[
  { "id": 1, "...": "..." },
  { "id": 2, "...": "..." }
]

Organizations#show is the one exception — it returns a JSON object mapping organization name to ID, not an array.

List vs. detail

Some resources have two representations:

List (GET /resources) — for Projects, a compact summary suitable for indexes; for Machines, Parts, and Tool Assemblies, the same nested shape as the detail view
Detail (GET /resources/:id) — full object with nested associations

For example, GET /projects returns compact {id, name, status, locked} summaries; GET /projects/8 returns the full project including jobs and operations. Machines and Parts return the same full shape on both index and show.

Read-only resources

Tool Assemblies are managed only in the Tooling Metrics UI (create and edit them there) and are read-only via the API — there is no POST, PATCH, or DELETE route for tool assemblies. A request to a write method on that path doesn’t match any route, so it won’t return a clean JSON error — expect a routing-level failure rather than a documented status code. Stick to GET for this resource.

Date and time format

All timestamps are returned as ISO 8601 strings in UTC:

"created_at": "2026-06-02T08:30:00Z"

Pass timestamps in the same format on write requests.

File attachments

File uploads (pictures, drawings, STEP models) are passed as Base64-encoded strings in the JSON body — not as multipart form data:

{
  "number": "P-0042",
  "model": "<base64-encoded-step-content>"
}

See the Parts reference for field names and an example.

Rate limits

60 requests per minute per token. Responses don’t carry X-RateLimit-* headers — the only rate-limit-related header is Retry-After, sent on a 429 response. See Rate limits.

Common integrations

Integration	What it does	Start here
CAM software	Read tool assemblies and cutting data; push projects after programming	CAM integration guide (coming soon). See the Reference for the endpoints available today.
ERP / MRP	Planned: sync inventory items and purchase orders. These endpoints are not available yet	ERP sync guide (coming soon). See Not yet available for what the API covers today.
Tool presetter	Planned: write measured offsets back to tools. Tool write endpoints are not available yet	Production automation guide (coming soon). See Not yet available for what the API covers today.
Custom automation	Planned: trigger pick lists and monitor tool cribs. Pick list creation is not available yet	Production automation guide (coming soon). See Not yet available for what the API covers today.

Not yet available

The API covers Organizations, Machines, Tool Assemblies, Parts, and Projects. It does not yet expose inventory items, physical tool status/location, pick lists, or purchase orders — those are UI-only today. If your integration needs stock levels or purchasing data, there’s currently no API path for it. Integration guides are not published yet; see the Reference for the endpoints available today.