# Flywheel Energy API
> Flywheel and rotational-energy dynamics as an API, computed locally and deterministically. The energy endpoint computes the rotational kinetic energy stored in a spinning body, E = ½·I·ω², together with its angular momentum L = I·ω, in joules, kilojoules and watt-hours — from a moment of inertia (given directly, or worked out from a shape, mass and dimension) and an angular speed given as rpm, radians per second or hertz, which it reports in all three. The inertia endpoint returns the moment of inertia about the central axis for the common shapes — solid disk and cylinder (½·m·r²), thin ring and hoop (m·r²), hollow cylinder (½·m·(r_out²+r_in²)), solid sphere (⅖·m·r²), hollow sphere (⅔·m·r²) and a rod about its centre (1/12·m·L²) or end (⅓·m·L²) — from a mass and a radius, diameter or length. The flywheel endpoint sizes a flywheel: give a target energy and an operating speed and it returns the required inertia I = 2E/ω², or give an inertia and a maximum and minimum rpm and it returns the energy delivered between them, ΔE = ½·I·(ω₁²−ω₂²), with the coefficient of fluctuation. Everything is computed locally and deterministically, so it is instant and private. Ideal for mechanical-engineering and energy-storage tools, motor, engine and powertrain design, kinetic-energy-recovery and physics-education apps. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is rotational energy and inertia; for bolt tightening torque use a torque API and for power-screw mechanics use a screw-jack 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/flywheel-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($74/Mo) — 1,546,000 calls/Mo, 40 req/s

## Endpoints

### Flywheel

#### `GET /v1/energy` — Rotational kinetic energy & angular momentum

**Parameters:**
- `inertia` (query, optional, string) — Moment of inertia (kg·m²) Example: `1.25`
- `shape` (query, optional, string) — Or shape (solid_disk, solid_sphere, …) Example: `solid_disk`
- `mass` (query, optional, string) — Mass for the shape (kg) Example: `10`
- `radius` (query, optional, string) — Radius for the shape (m) Example: `0.5`
- `rpm` (query, optional, string) — Angular speed (rpm) Example: `3000`
- `omega` (query, optional, string) — Or angular speed (rad/s)
- `hz` (query, optional, string) — Or angular speed (Hz)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flywheel-api/v1/energy?inertia=1.25&shape=solid_disk&mass=10&radius=0.5&rpm=3000"
```

**Response:**
```json
{
    "data": {
        "formula": "E = ½·I·ω²; L = I·ω; ω = rpm·2π/60.",
        "angular_speed": {
            "hz": 50,
            "rpm": 3000,
            "omega_rad_s": 314.159265
        },
        "inertia_source": "given",
        "kinetic_energy_kj": 61.68502751,
        "kinetic_energy_wh": 17.13472986,
        "kinetic_energy_joules": 61685.027507,
        "moment_of_inertia_kg_m2": 1.25,
        "angular_momentum_kg_m2_s": 392.699082
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.212Z",
        "request_id": "3d26438d-33e6-4ef9-85fb-b41e54236c03"
    },
    "status": "ok",
    "message": "Rotational kinetic energy",
    "success": true
}
```

#### `GET /v1/flywheel` — Flywheel sizing & energy delivered

**Parameters:**
- `energy` (query, optional, string) — Target energy (J) for required inertia Example: `50000`
- `rpm` (query, optional, string) — Operating speed (rpm) Example: `3000`
- `inertia` (query, optional, string) — Or inertia (kg·m²) for energy delivered
- `rpm_max` (query, optional, string) — Maximum rpm
- `rpm_min` (query, optional, string) — Minimum rpm

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flywheel-api/v1/flywheel?energy=50000&rpm=3000"
```

**Response:**
```json
{
    "data": {
        "mode": "required_inertia",
        "note": "Flywheel energy storage and sizing.",
        "formula": "I = 2E/ω²; ΔE = ½·I·(ω₁² − ω₂²).",
        "operating_speed": {
            "hz": 50,
            "rpm": 3000,
            "omega_rad_s": 314.159265
        },
        "target_energy_joules": 50000,
        "required_moment_of_inertia_kg_m2": 1.01321184
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.317Z",
        "request_id": "b4c28c7b-b331-4bc8-b4f0-bb708fb45e50"
    },
    "status": "ok",
    "message": "Flywheel sizing & energy delivered",
    "success": true
}
```

#### `GET /v1/inertia` — Moment of inertia of a shape

**Parameters:**
- `shape` (query, required, string) — solid_disk|thin_ring|hollow_cylinder|solid_sphere|rod_center|… Example: `solid_disk`
- `mass` (query, required, string) — Mass (kg) Example: `10`
- `radius` (query, optional, string) — Radius (m) Example: `0.5`
- `length` (query, optional, string) — Or length for a rod (m)
- `outer_radius` (query, optional, string) — Outer radius for hollow cylinder (m)
- `inner_radius` (query, optional, string) — Inner radius for hollow cylinder (m)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flywheel-api/v1/inertia?shape=solid_disk&mass=10&radius=0.5"
```

**Response:**
```json
{
    "data": {
        "shape": "solid_disk",
        "formula": "Solid disk / solid cylinder, I = ½·m·r²",
        "mass_kg": 10,
        "radius_m": 0.5,
        "moment_of_inertia_kg_m2": 1.25
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.408Z",
        "request_id": "a4e20de0-2fdf-43a3-bf6e-cc1930cf7b33"
    },
    "status": "ok",
    "message": "Moment of inertia of a shape",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "flywheel",
        "note": "Flywheel / rotational-energy dynamics — computed locally and deterministically, no key, no third-party service.",
        "shapes": [
            "solid_disk",
            "solid_cylinder",
            "thin_ring",
            "hoop",
            "thin_cylinder",
            "solid_sphere",
            "hollow_sphere",
            "rod_center",
            "rod_end",
            "point_mass",
            "hollow_cylinder"
        ],
        "endpoints": [
            "/v1/energy",
            "/v1/inertia",
            "/v1/flywheel",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.506Z",
        "request_id": "8c63be4b-b0c7-49eb-b8d2-de4583af69b1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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