# Pulley System API
> Pulley and block-and-tackle mechanics as an API, computed locally and deterministically. The advantage endpoint computes the mechanical advantage of a pulley system — the ideal MA equals the number of rope parts supporting the load, which is also the velocity ratio — and returns the effort needed to hold or raise a load, effort = load/(n·efficiency), the length of rope that must be pulled (n times the lift height) and the work in and out. The friction endpoint models a real block and tackle where every sheave loses a little tension: the mechanical advantage becomes MA = e·(1−eⁿ)/(1−e) for a per-sheave efficiency e (≈0.96 for a plain bearing, ≈0.98 for a ball bearing), so it returns the true MA, the overall efficiency and the extra effort friction costs you. The solve endpoint takes any two of the load, the effort and the number of rope parts and returns the third — for example, how many parts you need so a given person can raise a given load, or the heaviest load a winch can lift. Everything is computed locally and deterministically, so it is instant and private. Ideal for rigging, lifting and hoist-design tools, sailing, climbing and theatre-rigging apps, crane and winch sizing, and physics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is pulley and block-and-tackle mechanics; for lever and moment balance use a lever API and for rope-around-a-drum capstan friction use a capstan 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/pulley-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($22/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($69/Mo) — 750,000 calls/Mo, 40 req/s

## Endpoints

### Pulley

#### `GET /v1/advantage` — Mechanical advantage

**Parameters:**
- `segments` (query, required, string) — Rope parts supporting the load Example: `4`
- `load` (query, optional, string) — Load to raise (N) Example: `1000`
- `efficiency` (query, optional, string) — Overall efficiency (0–1, default 1) Example: `1`
- `distance` (query, optional, string) — Lift height (m) for rope travel & work Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pulley-api/v1/advantage?segments=4&load=1000&efficiency=1&distance=2"
```

**Response:**
```json
{
    "data": {
        "note": "Ideal MA equals the number of rope parts supporting the load (= velocity ratio). Effort = load/(n·efficiency).",
        "inputs": {
            "load": 1000,
            "distance": 2,
            "segments": 4,
            "efficiency": 1
        },
        "effort_n": 250,
        "work_input_j": 2000,
        "rope_pulled_m": 8,
        "work_output_j": 2000,
        "ideal_effort_n": 250,
        "velocity_ratio": 4,
        "overall_efficiency": 1,
        "ideal_mechanical_advantage": 4,
        "actual_mechanical_advantage": 4
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:28.315Z",
        "request_id": "9559b30c-273b-4569-a07a-c4f5133be7f1"
    },
    "status": "ok",
    "message": "Mechanical advantage",
    "success": true
}
```

#### `GET /v1/friction` — Sheave-friction MA

**Parameters:**
- `segments` (query, required, string) — Rope parts supporting the load Example: `4`
- `sheave_efficiency` (query, optional, string) — Per-sheave efficiency e (default 0.96) Example: `0.95`
- `load` (query, optional, string) — Load to raise (N) Example: `1000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pulley-api/v1/friction?segments=4&sheave_efficiency=0.95&load=1000"
```

**Response:**
```json
{
    "data": {
        "note": "Each sheave loses a fraction of the tension; MA = e·(1−eⁿ)/(1−e). e≈0.96 plain bearing, ≈0.98 ball bearing.",
        "inputs": {
            "load": 1000,
            "segments": 4,
            "sheave_efficiency": 0.95
        },
        "effort_n": 283.7377,
        "ideal_effort_n": 250,
        "friction_penalty_n": 33.7377,
        "overall_efficiency": 0.881095,
        "mechanical_advantage": 3.524381,
        "ideal_mechanical_advantage": 4
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:28.400Z",
        "request_id": "15def3ee-1618-4a30-8a68-3ceb1c1ffd39"
    },
    "status": "ok",
    "message": "Sheave-friction MA",
    "success": true
}
```

#### `GET /v1/solve` — Solve load / effort / parts

**Parameters:**
- `load` (query, optional, string) — Load (N) Example: `1000`
- `effort` (query, optional, string) — Available effort (N) Example: `300`
- `segments` (query, optional, string) — Rope parts
- `efficiency` (query, optional, string) — Overall efficiency (0–1, default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pulley-api/v1/solve?load=1000&effort=300&efficiency=1"
```

**Response:**
```json
{
    "data": {
        "mode": "solve_segments",
        "note": "Rope parts needed so the effort can raise the load. Rounded up to a whole number of parts.",
        "inputs": {
            "load": 1000,
            "effort": 300,
            "efficiency": 1
        },
        "segments_exact": 3.3333,
        "segments_required": 4
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:28.494Z",
        "request_id": "b17962af-a4f8-420b-bac2-7516b20bdacf"
    },
    "status": "ok",
    "message": "Solve load/effort/segments",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Forces in newtons, distance in metres. 'segments' is the number of rope parts supporting the moving block. Sheave efficiency e ≈ 0.96 plain, 0.98 ball-bearing.",
        "service": "pulley-api",
        "formulae": {
            "effort": "effort = load/(n·efficiency)",
            "ideal_ma": "MA = n (supporting rope parts) = velocity ratio",
            "friction_ma": "MA = e·(1−eⁿ)/(1−e)"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/solve": "Solve the missing one of load, effort or number of rope parts.",
            "GET /v1/friction": "Block-and-tackle MA with per-sheave friction: MA = e·(1−eⁿ)/(1−e).",
            "GET /v1/advantage": "Ideal mechanical advantage, effort, rope travel and work from the number of rope parts."
        },
        "description": "Pulley and block-and-tackle calculator: mechanical advantage, effort, velocity ratio and sheave-friction efficiency for rope-and-pulley lifting systems."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:28.591Z",
        "request_id": "4c632db1-0179-494b-98eb-68e75264ed4e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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