API: torsional load transfer

Computes named Florida District 7 or CDOT drilled-shaft torsional capacity plus a user-calibrated monotonic torque–rotation and depth-transfer response. The scientific basis is described in Torsional load transfer; the same analysis runs interactively at the torsion tool.

Endpoint

POST

https://api.pilecalc.com/v1/torsion

GET

/v1/torsion?key=…&req=…&fields=…(for header-less callers)

Set unitSystem explicitly. pile must describe a vertical, prismatic solid-circular drilled shaft with both E and G. Select the namedmethod, declare whether toe transfer is included, and provide a positiverotation50 for every soil layer and included toe. calibration must identify the evidence reference and maximum supported rotation; the requested curve may not extend beyond it. With groundwater,waterUnitWeight is mandatory.

Authentication, rate limits, and the error envelope are shared by every endpoint — see the API overview. Requests are unit-agnostic: any self-consistent unit system works, and results come back in the same units. The examples below use SI (m, kN, kPa, kN/m³).

Request fields

This table is generated from the same schema that validates the request, so it cannot drift. Where a field appears once per variant row, it belongs to that variant only.

Field	Type	Required	Constraints
`unitSystem`	"si" \| "us"	yes	Unit bundle for every dimensional input and output. "si": m, kN, kPa, kN/m³, kN·m, kN·m². "us": the kip–foot bundle — ft, kip, ksf, kip/ft³, kip·ft, kip·ft² (unit weights in kip/ft³, not pcf). Values are not converted, so every field must use the declared bundle.
`method`	"florida-district-7" \| "cdot-2004"	yes	Named ultimate torsional capacity method from FHWA-OR-RD-16-14. florida-district-7 ignores side resistance in the top 1.5 m and needs K for every cohesionless layer; cdot-2004 ignores the top 1.5 shaft diameters and computes K from L/D and φ.
`transferModel`	"user-calibrated-hyperbolic"	yes	Torque–rotation transfer model: a hyperbolic τ–θ law scaled by each layer's calibrated rotation50 (the only option).
`interactionModel`	"none" \| "florida-district-7-toe-normal-force-only"	yes	Axial–torsion interaction. Use none when appliedAxialLoad is 0; use florida-district-7-toe-normal-force-only when a nonzero axial load enters the Florida District 7 cohesionless-toe normal-force term.
`pile`	object	yes	Vertical, prismatic, solid-circular drilled shaft.
`pile.kind`	"uniform"	yes	Prismatic shaft of constant diameter (the only option).
`pile.length`	number	yes	> 0 — Shaft length from the head at the ground surface to the toe (m for si, ft for us).
`pile.diameter`	number	yes	> 0 — Shaft diameter D (m for si, ft for us).
`pile.elasticModulus`	number	yes	> 0 — Young's modulus E of the shaft (kPa for si, ksf for us).
`pile.shearModulus`	number	yes	> 0 — Shear modulus G of the shaft (kPa for si, ksf for us), used with J = πD⁴/32 for elastic twist along the shaft.
`pile.unitWeight`	number	yes	≥ 0 — Unit weight of the shaft material (kN/m³ for si, kip/ft³ for us), used for the effective shaft weight in the cohesionless-toe torque; must not be less than waterUnitWeight when the shaft extends below the water table.
`pile.displacement`	false	yes	Always false: the methods cover non-displacement drilled shafts only.
`soil`	object	yes	Soil profile for the shaft; rock layers are not supported.
`soil.layers[]`	object[]	yes	min 1 item — Soil layers ordered from the ground surface down: contiguous, starting at depth 0, and reaching the shaft toe.
`soil.layers[].type = "cohesive"`	variant	yes	Cohesive layer characterized by undrained shear strength.
`soil.layers[].top`	number	yes	≥ 0 — Depth of the layer top below the ground surface (m for si, ft for us); the first layer starts at 0 and each layer starts at the previous bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth of the layer bottom below the ground surface (m for si, ft for us); the last layer must reach the shaft toe.
`soil.layers[].gamma`	number	yes	> 0 — Total unit weight γ (kN/m³ for si, kip/ft³ for us).
`soil.layers[].cohesion`	number	no	≥ 0 — Undrained shear strength Su (kPa for si, ksf for us). Give exactly one of cohesion or qu. Florida District 7 applies only up to Su/Pa = 2.5.
`soil.layers[].qu`	number	no	≥ 0 — Unconfined compressive strength qu (kPa for si, ksf for us); Su is taken as qu/2. Give exactly one of cohesion or qu.
`soil.layers[].rotation50`	number	yes	> 0 — Calibrated rotation at which 50% of the layer's ultimate unit torsional resistance is mobilized (radians).
`soil.layers[].type = "cohesionless"`	variant	yes	Cohesionless layer characterized by friction angle.
`soil.layers[].top`	number	yes	≥ 0 — Depth of the layer top below the ground surface (m for si, ft for us); the first layer starts at 0 and each layer starts at the previous bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth of the layer bottom below the ground surface (m for si, ft for us); the last layer must reach the shaft toe.
`soil.layers[].gamma`	number	yes	> 0 — Total unit weight γ (kN/m³ for si, kip/ft³ for us).
`soil.layers[].phi`	number	yes	0 – 60 — Friction angle φ in degrees; the shaft–soil interface angle δ is taken equal to φ.
`soil.layers[].rotation50`	number	yes	> 0 — Calibrated rotation at which 50% of the layer's ultimate unit torsional resistance is mobilized (radians).
`soil.layers[].lateralEarthPressureCoefficient`	number	no	> 0 — Lateral earth pressure coefficient K. Required for florida-district-7, between K0 = 1 − sin φ and 1.75. Omit for cdot-2004, which computes K from L/D and φ.
`soil.waterTableDepth`	number	no	≥ 0 — Depth of the water table below the ground surface (m for si, ft for us); omit for a dry profile. Requires waterUnitWeight.
`soil.waterUnitWeight`	number	no	> 0 — Unit weight of water (kN/m³ for si, e.g. 9.81; kip/ft³ for us, e.g. 0.0624). Required when waterTableDepth is given.
`toe`	object	yes	Whether toe torsional resistance is included; an included toe needs its own rotation50.
`toe.mode = "excluded"`	variant	yes	Toe torsional resistance is ignored.
`toe.mode = "included"`	variant	yes	Toe torsional resistance is included, mobilized hyperbolically with toe rotation.
`toe.rotation50`	number	yes	> 0 — Calibrated toe rotation at which 50% of the ultimate toe torque is mobilized (radians).
`calibration`	object	yes	Declared evidence behind the rotation50 calibration and the rotation range it supports.
`calibration.reference`	string	yes	Citation or identifier of the evidence behind the rotation50 values (for example a load-test report); echoed in the response.
`calibration.maxRotation`	number	yes	0 – 0.2617993877991494 — Largest head rotation supported by the calibration evidence, in radians (at most 15°, about 0.2618).
`loading`	object	yes	Monotonic head-torque loading and torque–rotation curve controls.
`loading.type`	"monotonic"	yes	Monotonic loading (the only option; cyclic loading is not supported).
`loading.serviceTorque`	number	yes	> 0 — Service head torque at which rotation and stiffness are reported (kN·m for si, kip·ft for us); must be reached within maxRotation.
`loading.torqueStep`	number	yes	> 0 — Half-step ΔT of the centered difference for the service tangent stiffness (kN·m for si, kip·ft for us); at most 5% of serviceTorque.
`loading.maxRotation`	number	yes	0 – 0.2617993877991494 — Largest head rotation of the reported torque–rotation curve, in radians (at most 15°, about 0.2618); cannot exceed calibration.maxRotation.
`loading.rotationPoints`	number	yes	integer, 21 – 201 — Number of equally spaced points on the torque–rotation curve from zero to maxRotation inclusive.
`appliedAxialLoad`	number	yes	≥ 0 — Axial compression at the shaft head (kN for si, kip for us), 0 or positive. A nonzero value requires florida-district-7, an included toe in a cohesionless layer, and interactionModel florida-district-7-toe-normal-force-only.
`factorOfSafety`	number	yes	> 1 — Factor of safety applied to the total ultimate torque to give the allowable torque; greater than 1.
`segments`	number	yes	integer, 200 – 500 — Integration segments along the shaft for the fine run; a half-resolution run is compared against it.
`convergenceTolerance`	number	yes	0 – 0.03 — Maximum relative difference allowed between the fine and half-resolution results (ultimate capacity, torque at maxRotation, service rotation and tangent stiffness).

Response fields

Field	Type	Description
`capacity.shaft / .toe / .total`	number	Named ultimate shaft and toe components and their exact sum (moment units declared by unitSystem).
`capacity.allowable`	number	Total ultimate resistance divided by factorOfSafety.
`capacity.segments`	array	Depth intervals, layer index, ultimate interface resistance, side torque, and surface-exclusion flag.
`service`	object	Service torque and rotation, shaft/toe shares, secant stiffness, centered tangent stiffness, and tangent bracket.
`curve`	array	Strictly monotonic head torque–rotation points through the declared maximum rotation.
`depthTransfer`	array	Service-state rotation and internal torque from pile head to toe.
`equilibrium`	object	Head/shaft/toe torque balance and service-load residuals.
`convergence`	object	Fine and half-resolution meshes plus capacity, response, rotation, and tangent-stiffness differences.
`applicability`	object	Explicit monotonic/calibrated scope and the cyclic and axial-interaction exclusions.
`calibrationEvidence`	object	Echoed project calibration reference, supported maximum rotation, and a false extrapolation flag.
`method`	object	Stable method ID, FHWA edition, named capacity methods, response-model scope, and validation status.
`warnings`	string[]?	Plain-language notes where the published sources are silent, e.g. the sand-toe torque uses the buoyant shaft weight below the water table (FHWA-OR-RD-16-14 Eqs. 2.5/2.17 define W only as shaft weight).

Code examples

A complete, runnable request. Replace YOUR_API_KEY (or set PILECALC_API_KEY in your environment).

POST /v1/torsion

curl https://api.pilecalc.com/v1/torsion \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "florida-district-7",
  "transferModel": "user-calibrated-hyperbolic",
  "interactionModel": "none",
  "pile": {
    "kind": "uniform",
    "length": 6,
    "diameter": 1,
    "elasticModulus": 30000000,
    "shearModulus": 12500000,
    "unitWeight": 24,
    "displacement": false
  },
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 7,
        "gamma": 18,
        "cohesion": 50,
        "rotation50": 0.01
      }
    ]
  },
  "toe": {
    "mode": "excluded"
  },
  "calibration": {
    "reference": "Example only - replace with a project monotonic torsion test reference",
    "maxRotation": 0.08
  },
  "loading": {
    "type": "monotonic",
    "serviceTorque": 100,
    "torqueStep": 1,
    "maxRotation": 0.08,
    "rotationPoints": 41
  },
  "appliedAxialLoad": 0,
  "factorOfSafety": 3,
  "segments": 240,
  "convergenceTolerance": 0.02
}'

The GET variant returns capacity.total,capacity.allowable,service.rotation,service.tangentStiffness,equilibrium.relativeResidual as a plain-text CSV line — made for Excel's WEBSERVICE() and Sheets' IMPORTDATA() (see Use PileCalc in Excel). Omit fields to get the full JSON response.

Interpreting results

capacity.total is exactly shaft plus toe. The legacy side-friction-times-radius field is a comparison component and must not replace total.
service.secantStiffness reproduces the origin-to-service response;service.tangentStiffness is the centered local slope about that torque.
A response exists only when the service torque is bracketed, equilibrium closes, and all four fine/half-resolution comparisons pass the requested tolerance.
Nonzero axial load is legal only for the Florida District 7 cohesionless-toe normal-force term. The response does not represent generalized axial–torsional interaction.

Unsupported requests fail closed

Cyclic loading, rock, battered/tapered/displacement piles, uncalibrated layers, and unsupported combined loading return actionable validation or engine errors; no silent extrapolation is made.