# Getting started

Generate a token and make your first API request in under 5 minutes.

Source: https://support.toolingmetrics.com/en/api/getting-started/
Updated: 2026-10-29

**What you need:** A Tooling Metrics account with access to at least one organization.

The Tooling Metrics API is a JSON REST API over HTTPS. Every request requires a Bearer token.

## Step 1: Generate an API token

1. In Tooling Metrics, click your avatar at the bottom of the sidebar → **Setting** → **API Tokens** tab.
2. Click **New API Token**.
3. Enter a name for this token (e.g., `erp-integration`, `cam-plugin`).
4. Click **Create** — the token is shown once. Copy it immediately; it will not be shown again.

## Step 2: Find your organization ID

Most API endpoints require an `organization_id` path parameter. Retrieve yours:

```bash
curl https://api.toolingmetrics.com/v1/organizations \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Response — a map of organization name to numeric ID:

```json
{
  "Acme Manufacturing": 12,
  "Acme Tooling": 15
}
```

Use the numeric ID in all subsequent requests.

## Step 3: Make your first request

List machines in your organization:

```bash
curl https://api.toolingmetrics.com/v1/organizations/12/machines \
  -H "Authorization: Bearer YOUR_TOKEN"
```

A `200 OK` with a JSON array means authentication and scoping are working correctly.

## Step 4: Handle errors

All API errors return JSON. Most use an `errors` array:

```json
{ "errors": ["Description of what went wrong"] }
```

| Status | Cause | Action |
|---|---|---|
| `401` | Token missing/invalid, **or** token valid but not authorized for this resource, or for an `organization_id` that doesn't exist | Check the message: a missing token asks you to authenticate; an authorization failure says "You are not authorized to perform this action" |
| `404` | Record not found or belongs to a different organization | Verify the ID, and that the record belongs to the `organization_id` in the URL; an `organization_id` that doesn't exist answers `401`. Note: this error's body uses a singular `error` key, not `errors` |
| `422` | Validation failed | Read the `errors` array in the response |
| `429` | Rate limit exceeded | Wait `Retry-After` seconds and retry |

There is no `403` status in this API — both missing/invalid tokens and valid-but-unauthorized tokens return `401`, distinguished only by the error message. See [Errors](https://support.toolingmetrics.com/en/api/errors/) for the full picture, including the `error`/`errors` key inconsistency.

See [Errors](https://support.toolingmetrics.com/en/api/errors/) for the complete reference.

## Next steps

- [Concepts](https://support.toolingmetrics.com/en/api/concepts/) — organization scoping, pagination, date formats, and read-only resources
- Guides (coming soon) — step-by-step patterns for CAM integration, ERP sync, and production automation. Until then, see [Concepts](https://support.toolingmetrics.com/en/api/concepts/) for what the API covers today.
- [Reference](https://support.toolingmetrics.com/en/api/reference/) — complete endpoint documentation