# CNC Surface Finish API
> CNC surface-finishing maths as an API, computed locally and deterministically — the scallop, stepover and pass numbers a CNC machinist dials in for a smooth finish. The scallop endpoint gives the cusp height a ball-nose tool leaves between passes, h = R − √(R² − (stepover/2)²), so a half-inch ball at a 0.05-inch stepover leaves about a 1.25-thou ridge — tighter stepover, smaller cusp, far more passes. The stepover endpoint inverts it: the stepover for a target scallop height, 2·√(R² − (R−h)²), reported also as a percent of tool diameter (fine finishing runs ~4–10 %) so it carries across jobs — and a bigger finishing ball reaches the same finish at a wider, faster stepover. The passes endpoint turns a surface into work: passes = width ÷ stepover rounded up plus one, the total cutting travel, and the cutting time at a given feed rate — surfacing a 4×6-inch area at a 0.05-inch stepover is 81 passes and 486 inches of travel, under five minutes at 100 ipm. Everything is computed locally and deterministically, so it is instant and private. Ideal for CNC and CAM apps, machinist and toolpath calculators, maker and job-shop tools, and engineering aids. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For cutting speed, feed and rpm use a machining API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/cncfinish-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 13,100 calls/Mo, 6 req/s
- **Pro** ($18/Mo) — 82,500 calls/Mo, 15 req/s
- **Mega** ($52/Mo) — 266,000 calls/Mo, 36 req/s

## Endpoints

### CNC Finish

#### `GET /v1/passes` — Passes and time to surface an area

**Parameters:**
- `width_in` (query, required, string) — Surface width in inches Example: `4`
- `length_in` (query, required, string) — Pass length in inches Example: `6`
- `stepover_in` (query, required, string) — Stepover in inches Example: `0.05`
- `feed_ipm` (query, optional, string) — Feed rate in inches/min Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cncfinish-api/v1/passes?width_in=4&length_in=6&stepover_in=0.05&feed_ipm=100"
```

**Response:**
```json
{
    "data": {
        "note": "Passes to cover a width = width ÷ stepover, rounded up, plus one to finish the far edge; total cutting travel = passes × the pass length. Halving the stepover doubles the passes and the time, which is why finish stepover is the big lever on a long surfacing job.",
        "inputs": {
            "width_in": 4,
            "length_in": 6,
            "stepover_in": 0.05
        },
        "passes": 81,
        "total_travel_in": 486,
        "cutting_time_min": 4.86
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.032Z",
        "request_id": "ff2ebb1d-7ce2-485c-9990-366cee5dc4b1"
    },
    "status": "ok",
    "message": "Passes & time",
    "success": true
}
```

#### `GET /v1/scallop` — Scallop height from stepover

**Parameters:**
- `tool_diameter_in` (query, required, string) — Ball-nose diameter in inches Example: `0.5`
- `stepover_in` (query, required, string) — Stepover in inches Example: `0.05`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cncfinish-api/v1/scallop?tool_diameter_in=0.5&stepover_in=0.05"
```

**Response:**
```json
{
    "data": {
        "note": "Scallop (cusp) height = R − √(R² − (stepover/2)²) for a ball-nose tool — the little ridge left between finishing passes. Tighter stepover means a smaller scallop and a smoother finish but far more passes and time. A 0.5-inch ball at 0.05-inch stepover leaves about a 1.25-thou cusp.",
        "inputs": {
            "stepover_in": 0.05,
            "tool_diameter_in": 0.5
        },
        "scallop_height_in": 0.001253,
        "scallop_height_thou": 1.25
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.127Z",
        "request_id": "8e202115-3b47-4187-9d2e-db77f3de9469"
    },
    "status": "ok",
    "message": "Scallop height",
    "success": true
}
```

#### `GET /v1/stepover` — Stepover for a target scallop

**Parameters:**
- `tool_diameter_in` (query, required, string) — Ball-nose diameter in inches Example: `0.5`
- `target_scallop_in` (query, required, string) — Target scallop height in inches Example: `0.001`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cncfinish-api/v1/stepover?tool_diameter_in=0.5&target_scallop_in=0.001"
```

**Response:**
```json
{
    "data": {
        "note": "Stepover for a target scallop = 2·√(R² − (R−h)²). Express it as a percent of the tool diameter to carry across jobs — fine finishing runs ~4–10 % of diameter. A bigger ball reaches the same finish at a wider stepover, so a large finishing ball is faster than a small one for the same smoothness.",
        "inputs": {
            "tool_diameter_in": 0.5,
            "target_scallop_in": 0.001
        },
        "stepover_in": 0.04468,
        "stepover_pct_of_dia": 8.9
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.224Z",
        "request_id": "ea2562e4-483c-46c3-9af1-280cf5df3cbb"
    },
    "status": "ok",
    "message": "Stepover",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cncfinish-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Inches & ipm, ball-nose tools. h = R − √(R²−(so/2)²); so = 2√(R²−(R−h)²); passes = ⌈width/stepover⌉+1. For cutting speed/feed/rpm use a machining API.",
        "service": "cncfinish-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/passes": "Passes and travel to surface a width, with optional time at a feed.",
            "GET /v1/scallop": "Scallop (cusp) height from tool diameter and stepover.",
            "GET /v1/stepover": "Stepover for a target scallop height."
        },
        "description": "CNC surface-finishing maths: scallop height from a ball-nose and stepover, the stepover for a target finish, and the passes/time to surface an area."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.299Z",
        "request_id": "93e551a8-2b9e-4b74-a49e-c7f3cd6b9dfd"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/cncfinish-api
OpenAPI spec: https://www.oanor.com/api/cncfinish-api/openapi.json