# Winch Drum API
> Winch and cable-drum maths as an API, computed locally and deterministically — the rope-capacity, line-pull and rope-out numbers a winch operator, rigger or recovery driver works a drum with. The capacity endpoint gives the rope a drum holds by exact layer geometry: the sum over every full layer of the turns per layer × π × that layer's mean wrap diameter, where turns per layer = drum width ÷ rope diameter and the number of layers = the flange-to-barrel depth ÷ rope diameter — a 10-inch barrel, 20-inch flange, 12-inch-wide drum on half-inch rope holds about 940 ft over 10 layers. The layer-pull endpoint shows why pull falls as the drum fills: the rated pull is for the bare-drum first layer, and as rope piles on, the growing lever arm cuts the line pull and raises the line speed in the same ratio — pull × (first-layer diameter ÷ this layer's diameter) — so the top layer of a deep drum can pull barely half the bottom-layer rating, which is why you spool off to bare drum for a hard pull or add a snatch block. The length-at-layer endpoint gives the rope wound after a number of full layers, for marking the rope or knowing how much line is out. Everything is computed locally and deterministically, so it is instant and private. Ideal for winch- and hoist-sizing tools, recovery and off-road apps, marine and industrial-rigging utilities, and engineering calculators. Pure local computation — no key, no third-party service, instant. Geometric estimate — allow for nesting and freeboard. 3 compute endpoints. For capstan friction use a capstan API; for block-and-tackle a pulley 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/winch-api/..."
```

## Pricing
- **Free** (Free) — 4,850 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 49,000 calls/Mo, 6 req/s
- **Pro** ($40/Mo) — 205,500 calls/Mo, 15 req/s
- **Mega** ($122/Mo) — 1,108,000 calls/Mo, 40 req/s

## Endpoints

### Winch

#### `GET /v1/capacity` — Rope capacity, layers and turns

**Parameters:**
- `barrel_diameter_in` (query, required, string) — Barrel (core) diameter (in) Example: `10`
- `flange_diameter_in` (query, required, string) — Flange diameter (in) Example: `20`
- `drum_width_in` (query, required, string) — Drum width between flanges (in) Example: `12`
- `rope_diameter_in` (query, required, string) — Rope diameter (in) Example: `0.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winch-api/v1/capacity?barrel_diameter_in=10&flange_diameter_in=20&drum_width_in=12&rope_diameter_in=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "The rope a drum holds = the sum, over every full layer, of the turns per layer × π × that layer's mean wrap diameter. Turns per layer = drum width ÷ rope diameter; the number of layers = the flange-to-barrel depth ÷ rope diameter. Each outer layer holds more because its circumference is larger — which is also why the line pulls weaker and faster as it fills (see /v1/layer-pull). Real capacity is a touch less for nesting and freeboard.",
        "inputs": {
            "drum_width_in": 12,
            "rope_diameter_in": 0.5,
            "barrel_diameter_in": 10,
            "flange_diameter_in": 20
        },
        "full_layers": 10,
        "turns_per_layer": 24,
        "rope_capacity_ft": 942.5
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:56.963Z",
        "request_id": "2cf0cc87-9d60-4dca-a240-51986454ced0"
    },
    "status": "ok",
    "message": "Drum capacity",
    "success": true
}
```

#### `GET /v1/layer-pull` — Line pull and speed at a layer

**Parameters:**
- `bare_drum_pull_lb` (query, required, string) — Bare-drum (rated) line pull (lb) Example: `10000`
- `barrel_diameter_in` (query, required, string) — Barrel diameter (in) Example: `10`
- `rope_diameter_in` (query, required, string) — Rope diameter (in) Example: `0.5`
- `layer` (query, required, string) — Wrap layer number Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winch-api/v1/layer-pull?bare_drum_pull_lb=10000&barrel_diameter_in=10&rope_diameter_in=0.5&layer=5"
```

**Response:**
```json
{
    "data": {
        "note": "A winch's rated pull is for the first (bare-drum) layer; as rope piles on, the effective lever arm grows, so the line pull falls and the line speed rises in the same ratio — pull × (first-layer diameter ÷ this layer's diameter). On a deep drum the top layer can pull barely half the bottom-layer rating, which is why you spool off to the bare drum for a hard pull, or add a snatch block.",
        "inputs": {
            "layer": 5,
            "rope_diameter_in": 0.5,
            "bare_drum_pull_lb": 10000,
            "barrel_diameter_in": 10
        },
        "line_speed_factor": 1.381,
        "effective_line_pull_lb": 7241.4,
        "layer_mean_diameter_in": 14.5
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:57.071Z",
        "request_id": "38ee8458-d033-4f1f-b82a-76262e800d8e"
    },
    "status": "ok",
    "message": "Layer pull",
    "success": true
}
```

#### `GET /v1/length-at-layer` — Rope length at a number of layers

**Parameters:**
- `barrel_diameter_in` (query, required, string) — Barrel diameter (in) Example: `10`
- `drum_width_in` (query, required, string) — Drum width (in) Example: `12`
- `rope_diameter_in` (query, required, string) — Rope diameter (in) Example: `0.5`
- `layers_wound` (query, required, string) — Full layers wound Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winch-api/v1/length-at-layer?barrel_diameter_in=10&drum_width_in=12&rope_diameter_in=0.5&layers_wound=5"
```

**Response:**
```json
{
    "data": {
        "note": "The rope wound on the drum after a given number of full layers — handy for marking the rope or knowing how much is out: it is the same layer-by-layer sum as the full capacity, stopped at the layers you have spooled. Subtract it from the total length to know how much line is deployed, useful for reach and for staying off the last few drum wraps that must always remain anchored.",
        "inputs": {
            "layers_wound": 5,
            "drum_width_in": 12,
            "rope_diameter_in": 0.5,
            "barrel_diameter_in": 10
        },
        "rope_length_ft": 392.7,
        "turns_per_layer": 24
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:57.152Z",
        "request_id": "9f9254a9-50fd-4418-9aa6-30314aff7e0e"
    },
    "status": "ok",
    "message": "Length at layer",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Inches (drum/rope), feet (rope). capacity = Σ turns·π·mean-dia per layer; turns/layer = width/rope; layers = (flange−barrel)/2/rope; pull = bare-pull·(first-layer dia/this-layer dia). For capstan friction use a capstan API; for block-and-tackle a pulley API.",
        "service": "winch-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/capacity": "Rope capacity, layers and turns from the drum and rope size.",
            "GET /v1/layer-pull": "Effective line pull and speed at a wrap layer.",
            "GET /v1/length-at-layer": "Rope length wound at a number of full layers."
        },
        "description": "Winch / cable-drum maths: rope capacity by layer geometry, line pull and speed by layer, and rope length at a layer."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:57.227Z",
        "request_id": "c54a74e0-1a1f-43f6-8a5b-5e48ee68acef"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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