{"openapi":"3.1.0","info":{"title":"Hydraulic Cylinder API","version":"1.0.0","description":"Hydraulic-cylinder engineering maths as an API, computed locally and deterministically — the force, speed and oil-volume numbers a fluid-power designer, machine builder or hydraulics technician sizes a cylinder with. The force endpoint gives the push and pull from the bore, rod diameter and working pressure: extending, the oil acts on the full bore area, so the cylinder is strongest pushing out; retracting, it acts only on the annulus left by the rod, giving less force — a 100 mm bore with a 56 mm rod at 160 bar pushes about 125.7 kN out but pulls only 86.3 kN back, which is why a press or an excavator does its hard work on the extend stroke. The speed endpoint gives the piston speed from the pump flow (speed = flow ÷ area), so extending is the slower stroke and retracting the faster, the trade-off every circuit designer balances against force. The volume endpoint gives the swept oil volume per stroke for extend and retract, the rod displacement and the bore-to-annulus area ratio — the differential (regeneration) ratio used to speed the extend stroke in a regen circuit — so the pump, tank and lines can be sized for the larger volume. Everything is computed locally and deterministically, so it is instant and private. Ideal for fluid-power and machine-design tools, hydraulics-sizing calculators, mobile- and industrial-equipment utilities, and engineering apps. Pure local computation — no key, no third-party service, instant. Ideal-area estimates — allow for friction, back-pressure and efficiency. 3 compute endpoints. For Pascal force-multiplication use a hydraulics API; for valve sizing a valve-flow (Cv/Kv) API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/hydrauliccylinder-api","description":"oanor gateway"}],"tags":[{"name":"Cylinder"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/force":{"get":{"operationId":"get_v1_force","tags":["Cylinder"],"summary":"Extend and retract force","description":"","parameters":[{"name":"bore_mm","in":"query","required":true,"description":"Bore (piston) diameter (mm)","schema":{"type":"string"},"example":"100"},{"name":"rod_mm","in":"query","required":true,"description":"Rod diameter (mm)","schema":{"type":"string"},"example":"56"},{"name":"pressure_bar","in":"query","required":true,"description":"Working pressure (bar)","schema":{"type":"string"},"example":"160"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Force = pressure × piston area. Extending, the oil pushes on the full bore area, so the cylinder is strongest pushing out; retracting, it acts only on the annulus left by the rod, giving less force. That is why a press or a digging machine does its hard work on the extend stroke. The same pressure on a bigger bore gives proportionally more force (area grows with the diameter squared).","inputs":{"rod_mm":56,"bore_mm":100,"pressure_bar":160},"bore_area_mm2":7854,"extend_force_kn":125.66,"annulus_area_mm2":5391,"retract_force_kn":86.26},"meta":{"timestamp":"2026-06-06T23:53:53.137Z","request_id":"4c0ea757-b3ab-4fd0-b751-876514bf3ab7"},"status":"ok","message":"Cylinder force","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/speed":{"get":{"operationId":"get_v1_speed","tags":["Cylinder"],"summary":"Piston speed from flow","description":"","parameters":[{"name":"bore_mm","in":"query","required":true,"description":"Bore diameter (mm)","schema":{"type":"string"},"example":"100"},{"name":"rod_mm","in":"query","required":true,"description":"Rod diameter (mm)","schema":{"type":"string"},"example":"56"},{"name":"flow_lpm","in":"query","required":true,"description":"Oil flow (L/min)","schema":{"type":"string"},"example":"30"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Piston speed = oil flow ÷ piston area. Extending fills the full bore, so for a given pump flow the extend stroke is the slower one; retracting fills only the smaller annulus, so it moves faster (and needs a bigger flow path for the oil leaving the bore side). Speed and force trade off — the same flow and pressure give a fast light stroke or a slow strong one depending on the area.","inputs":{"rod_mm":56,"bore_mm":100,"flow_lpm":30},"extend_speed_mm_s":63.7,"retract_speed_mm_s":92.7},"meta":{"timestamp":"2026-06-06T23:53:53.233Z","request_id":"8934722f-4d71-4aac-b1e4-10469578bab6"},"status":"ok","message":"Piston speed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/volume":{"get":{"operationId":"get_v1_volume","tags":["Cylinder"],"summary":"Swept volume per stroke","description":"","parameters":[{"name":"bore_mm","in":"query","required":true,"description":"Bore diameter (mm)","schema":{"type":"string"},"example":"100"},{"name":"rod_mm","in":"query","required":true,"description":"Rod diameter (mm)","schema":{"type":"string"},"example":"56"},{"name":"stroke_mm","in":"query","required":true,"description":"Stroke length (mm)","schema":{"type":"string"},"example":"500"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The oil drawn to extend = full bore area × stroke; to retract = annulus area × stroke. The difference is the volume the rod takes up, and the bore-to-annulus area ratio is the cylinder's differential (regeneration) ratio — feeding the rod-side oil back to the bore in a regen circuit speeds the extend stroke at the cost of force. Size the pump and tank for the larger (extend) volume.","inputs":{"rod_mm":56,"bore_mm":100,"stroke_mm":500},"area_ratio":1.457,"extend_volume_l":3.927,"retract_volume_l":2.695,"rod_displacement_l":1.232},"meta":{"timestamp":"2026-06-06T23:53:53.330Z","request_id":"520a3578-306a-4210-9e14-2209e26b75ef"},"status":"ok","message":"Swept volume","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"Metric (mm, bar, L/min, kN, mm/s, L). Force = P×area (bore for extend, annulus for retract); speed = flow÷area; volume = area×stroke. For Pascal force-multiplication use a hydraulics API; for valve sizing a valve-flow (Cv/Kv) API.","service":"hydrauliccylinder-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/force":"Extend (bore) and retract (annulus) force at a working pressure.","GET /v1/speed":"Piston extend/retract speed from the pump flow.","GET /v1/volume":"Swept volume per stroke and the differential area ratio."},"description":"Hydraulic-cylinder maths: extend/retract force from bore, rod and pressure; piston speed from oil flow; and swept volume per stroke."},"meta":{"timestamp":"2026-06-06T23:53:53.429Z","request_id":"50c2cd5d-bd41-4f01-8a4d-26faccde17a2"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5100,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1240,"monthly_call_quota":54000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3850,"monthly_call_quota":229000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":11800,"monthly_call_quota":1170000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/hydrauliccylinder-api"}