# Screw Jack API
> Power-screw (lead-screw and screw-jack) mechanics as an API, computed locally and deterministically. The torque endpoint computes the torque to raise and to lower a load on a power screw from the load, the mean thread diameter, the lead (given directly or as pitch × starts) and the coefficient of friction: T_raise = (W·dm/2)·(L + π·μ′·dm)/(π·dm − μ′·L), with the matching lower torque, the lead angle, the efficiency (W·L ÷ 2π·T_raise) and whether the screw is self-locking (it is when the effective friction is at least the tangent of the lead angle). Square threads are the default; pass a thread angle (for example 29° for an ACME thread) and it applies the effective friction μ/cos(half-angle). The effort endpoint turns that torque into the hand force on a lever or handle and the resulting mechanical advantage. The travel endpoint relates turns, lift distance and — with an rpm — the linear speed and time. Lengths are in millimetres, load in newtons and torque in newton-metres. Everything is computed locally and deterministically, so it is instant and private. Thread friction only — add collar/thrust friction separately. Ideal for machine-design and mechanism tools, jack, press, vice and clamp design, maker and robotics projects, and engineering calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is power-screw mechanics; for the geometry of a screw thread use a thread API and for bolt tightening torque use a torque 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/screwjack-api/..."
```

## Pricing
- **Free** (Free) — 1,500 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 18,000 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 120,000 calls/Mo, 15 req/s
- **Mega** ($74/Mo) — 600,000 calls/Mo, 40 req/s

## Endpoints

### ScrewJack

#### `GET /v1/effort` — Handle effort & mechanical advantage

**Parameters:**
- `load` (query, required, string) — Axial load W (N) Example: `10000`
- `mean_diameter` (query, required, string) — Mean diameter (mm) Example: `22`
- `lead` (query, optional, string) — Lead (or pitch+starts) Example: `5`
- `friction` (query, optional, string) — Friction (default 0.15) Example: `0.15`
- `thread_angle` (query, optional, string) — Thread angle deg Example: `0`
- `lever_arm` (query, required, string) — Handle/lever arm (mm) Example: `300`
- `direction` (query, optional, string) — raise|lower (default raise) Example: `raise`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/screwjack-api/v1/effort?load=10000&mean_diameter=22&lead=5&friction=0.15&thread_angle=0&lever_arm=300&direction=raise"
```

**Response:**
```json
{
    "data": {
        "note": "Effort = torque ÷ lever arm. Mechanical advantage = load ÷ effort.",
        "load_N": 10000,
        "torque": {
            "N_m": 24.7261,
            "N_mm": 24726.06
        },
        "effort_N": 82.4202,
        "direction": "raise",
        "lever_arm_mm": 300,
        "mechanical_advantage": 121.329
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:03.111Z",
        "request_id": "e2da44b5-e6dd-45f7-be8a-7ebaf6fc74be"
    },
    "status": "ok",
    "message": "Handle effort & mechanical advantage",
    "success": true
}
```

#### `GET /v1/torque` — Raise/lower torque & efficiency

**Parameters:**
- `load` (query, required, string) — Axial load W (N) Example: `10000`
- `mean_diameter` (query, required, string) — Mean thread diameter dm (mm) Example: `22`
- `lead` (query, optional, string) — Lead (mm) (or pitch+starts) Example: `5`
- `pitch` (query, optional, string) — Thread pitch
- `starts` (query, optional, string) — Number of starts
- `friction` (query, optional, string) — Coefficient of friction (default 0.15) Example: `0.15`
- `thread_angle` (query, optional, string) — Thread angle deg (0 square, 29 ACME) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/screwjack-api/v1/torque?load=10000&mean_diameter=22&lead=5&friction=0.15&thread_angle=0"
```

**Response:**
```json
{
    "data": {
        "note": "Square thread by default (thread_angle=0); pass thread_angle=29 for ACME. Excludes collar/thrust-bearing friction.",
        "load_N": 10000,
        "formula": "T_raise = (W·dm/2)·(L+π·μ'·dm)/(π·dm−μ'·L); efficiency = W·L/(2π·T_raise); self-locking when μ' ≥ tanλ.",
        "lead_mm": 5,
        "friction": 0.15,
        "efficiency": 0.32184,
        "lower_torque": {
            "N_m": 8.4506,
            "N_mm": 8450.55
        },
        "raise_torque": {
            "N_m": 24.7261,
            "N_mm": 24726.06
        },
        "self_locking": true,
        "lead_angle_deg": 4.1377,
        "mean_diameter_mm": 22,
        "thread_angle_deg": 0,
        "effective_friction": 0.15,
        "efficiency_percent": 32.18
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:03.220Z",
        "request_id": "3b886b71-3da5-43d2-84e5-7d2ee53e5314"
    },
    "status": "ok",
    "message": "Raise/lower torque & efficiency",
    "success": true
}
```

#### `GET /v1/travel` — Turns, distance & speed

**Parameters:**
- `lead` (query, optional, string) — Lead (or pitch+starts) Example: `5`
- `pitch` (query, optional, string) — Pitch
- `starts` (query, optional, string) — Starts
- `distance` (query, optional, string) — Lift distance (mm) Example: `100`
- `turns` (query, optional, string) — Or number of turns
- `rpm` (query, optional, string) — Rotation speed (for linear speed) Example: `60`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/screwjack-api/v1/travel?lead=5&distance=100&rpm=60"
```

**Response:**
```json
{
    "data": {
        "rpm": 60,
        "note": "Turns = distance ÷ lead. Linear speed = rpm × lead.",
        "turns": 20,
        "lead_mm": 5,
        "distance_mm": 100,
        "time_seconds": 20,
        "linear_speed_mm_s": 5,
        "linear_speed_mm_min": 300
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:03.318Z",
        "request_id": "7bea14ca-8029-4c69-9264-fda6f1838dd6"
    },
    "status": "ok",
    "message": "Turns, distance & speed",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "screwjack",
        "note": "Power-screw (lead-screw / screw-jack) mechanics — computed locally and deterministically, no key, no third-party service.",
        "defaults": {
            "friction": 0.15,
            "thread_angle_deg": 0
        },
        "endpoints": [
            "/v1/torque",
            "/v1/effort",
            "/v1/travel",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:03.406Z",
        "request_id": "6b0968f4-ffb3-498f-9b73-83e45c25ed82"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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