# Concepts Organization scoping, request/response shape, date formats, file attachments, and what's not yet available. Source: https://support.toolingmetrics.com/en/api/concepts/ Updated: 2026-10-29 ## 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](https://support.toolingmetrics.com/en/api/authentication/). ## Authentication All requests require a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` 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](https://support.toolingmetrics.com/en/api/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](https://support.toolingmetrics.com/en/api/reference/) page instead of relying on pages. List responses are bare JSON arrays — no envelope wrapper: ```json [ { "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: ```json "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: ```json { "number": "P-0042", "model": "" } ``` See the [Parts](https://support.toolingmetrics.com/en/api/reference/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](https://support.toolingmetrics.com/en/api/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](https://support.toolingmetrics.com/en/api/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](#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](#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](#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](https://support.toolingmetrics.com/en/api/reference/) for the endpoints available today.