URL gốc
API chạy trên tên miền phụ riêng, không phải một đường dẫn bên dưới ứng dụng chính:
https://api.toolingmetrics.com/v1
Phạm vi tổ chức
Mọi tài nguyên trong Tooling Metrics đều thuộc về một tổ chức. Phần lớn endpoint cần đoạn đường dẫn organization_id:
GET /v1/organizations/:organization_id/machines GET /v1/organizations/:organization_id/parts
Lấy ID tổ chức của bạn từ GET /v1/organizations. Yêu cầu tham chiếu đến bản ghi thuộc tổ chức khác sẽ trả về 404 Not Found.
Truyền đúng một organization_id mà bạn là thành viên vẫn chưa đủ — vai trò của bạn với từng loại tài nguyên còn giới hạn những bản ghi bạn xem được. Xem phần “Phạm vi phân quyền” trong Xác thực.
Xác thực
Mọi yêu cầu đều cần một Bearer token trong header Authorization:
Authorization: Bearer <your-token>
Khóa API là của cá nhân — tạo và thu hồi tại tab Khóa API trong cài đặt tài khoản (ảnh đại diện → Cài đặt), không phải ở khu vực quản trị tổ chức. Mỗi khóa có đúng quyền truy cập của người dùng đã tạo ra nó. Xem Xác thực.
Không phân trang
Các endpoint danh sách (index, search) không phân trang — chúng trả về mọi bản ghi khớp trong một phản hồi duy nhất. Không có tham số page hay per_page. Nếu tổ chức của bạn có rất nhiều bản ghi của một loại, hãy tính đến khả năng thân phản hồi rất lớn; lọc bằng các tham số truy vấn riêng của từng tài nguyên được mô tả trong mỗi trang tham khảo thay vì trông vào phân trang.
Phản hồi danh sách là mảng JSON trần — không có lớp bọc ngoài:
[ { "id": 1, "...": "..." }, { "id": 2, "...": "..." } ]
Organizations#show là ngoại lệ duy nhất — endpoint này trả về một đối tượng JSON ánh xạ tên tổ chức sang ID, không phải một mảng.
Danh sách và chi tiết
Một số tài nguyên có hai dạng biểu diễn:
- Danh sách (
GET /resources) — với dự án là bản tóm tắt gọn phù hợp cho trang danh sách; với máy gia công, chi tiết và mô hình dụng cụ là cùng cấu trúc lồng nhau như dạng chi tiết - Chi tiết (
GET /resources/:id) — đối tượng đầy đủ kèm các liên kết lồng nhau
Ví dụ: GET /projects trả về các bản tóm tắt gọn {id, name, status, locked}; GET /projects/8 trả về dự án đầy đủ, gồm cả nguyên công và bước gia công. Máy gia công và chi tiết trả về cùng cấu trúc đầy đủ ở cả index lẫn show.
Tài nguyên chỉ đọc
Mô hình dụng cụ chỉ được quản lý trong giao diện Tooling Metrics (tạo và chỉnh sửa ở đó) và là tài nguyên chỉ đọc qua API — không có route POST, PATCH hay DELETE cho mô hình dụng cụ. Yêu cầu dùng phương thức ghi trên đường dẫn này không khớp route nào, nên sẽ không trả về lỗi JSON gọn gàng — hãy chờ đợi một lỗi ở tầng định tuyến thay vì một mã trạng thái được mô tả trong tài liệu. Chỉ dùng GET cho tài nguyên này.
Định dạng ngày giờ
Mọi mốc thời gian được trả về dưới dạng chuỗi ISO 8601 theo giờ UTC:
"created_at": "2026-06-02T08:30:00Z"
Truyền mốc thời gian theo cùng định dạng trong các yêu cầu ghi.
Tệp đính kèm
Tệp tải lên (hình ảnh, bản vẽ, mô hình STEP) được truyền dưới dạng chuỗi mã hóa Base64 trong thân JSON — không dùng dữ liệu biểu mẫu multipart:
{ "number": "P-0042", "model": "<base64-encoded-step-content>" }
Xem trang tham khảo Chi tiết để biết tên trường và ví dụ.
Giới hạn tần suất
60 yêu cầu mỗi phút cho mỗi khóa. Phản hồi không có các header X-RateLimit-* — header duy nhất liên quan đến giới hạn tần suất là Retry-After, được gửi kèm phản hồi 429. Xem Giới hạn tần suất.
Chưa có
API hiện bao gồm tổ chức, máy gia công, mô hình dụng cụ, chi tiết và dự án. API chưa cung cấp hàng hóa tồn kho, trạng thái/vị trí của dụng cụ thực tế, phiếu xuất kho hay đơn mua hàng — hiện những dữ liệu này chỉ có trên giao diện. Nếu tích hợp của bạn cần mức tồn kho hoặc dữ liệu mua hàng, hiện chưa có đường API nào cho việc đó. Các hướng dẫn tích hợp chưa được phát hành; xem Tham khảo để biết các endpoint hiện có.