API: slope stabilization

POST /v1/slope and GET /v1/slope run the strict pile-row demand/capacity method. The request requires the named applied-displacement and NAVFAC/Reese– O'Neill component methods, a complete lateral and axial pile/soil model, a declared wide-spacing row, explicit numerical controls, and an ordered demand for every candidate surface. See Slope stabilization for the scientific boundary.

Endpoint

POST

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

GET

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

method, axial.method, unitSystem, water unit weight where applicable, the movement cap, and all solver controls are required. Candidate surfaces use { id, slidingDepth, distributedDemand }. Demand is force per unit row width in the declared SI or US bundle; total demand is calculated with row.tributaryWidth.

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
`method`	"applied-displacement-independent-wide-spacing"	yes
`lateral`	object	yes
`lateral.pile`	object	yes
`lateral.pile.kind = "uniform"`	variant	no
`lateral.pile.length`	number	yes	> 0
`lateral.pile.diameter`	number	yes	> 0
`lateral.pile.ei`	number	yes	> 0
`lateral.pile.groundSurfaceDepth`	number	no	≥ 0
`lateral.pile.kind = "sectioned"`	variant	yes
`lateral.pile.sections`	object \| object[]	yes	min 1 item
`lateral.pile.groundSurfaceDepth`	number	no	≥ 0
`lateral.soil`	object	yes
`lateral.soil.layers[]`	object[]	yes	min 1 item
`lateral.soil.layers[].model = "soft-clay"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].model = "stiff-clay-above-water"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].k`	number	no	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "stiff-clay-below-water"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "sand-reese"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "sand-api"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "weak-rock"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].qu`	number	yes	> 0
`lateral.soil.layers[].quBottom`	number	no	> 0
`lateral.soil.layers[].eir`	number	yes	> 0
`lateral.soil.layers[].eirBottom`	number	no	> 0
`lateral.soil.layers[].rqd`	number	yes	0 – 100
`lateral.soil.layers[].rqdBottom`	number	no	0 – 100
`lateral.soil.layers[].krm`	number	no	> 0
`lateral.soil.layers[].model = "elastic"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].esTop`	number	yes	≥ 0
`lateral.soil.layers[].esBottom`	number	no	≥ 0
`lateral.soil.layers[].model = "user"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].es`	number	no	≥ 0
`lateral.soil.layers[].curves[]`	object[]	no
`lateral.soil.layers[].curves[].depth`	number	yes	≥ 0
`lateral.soil.layers[].curves[].points[]`	object[]	yes	min 2 items
`lateral.soil.layers[].curves[].points[].y`	number	yes	≥ 0
`lateral.soil.layers[].curves[].points[].p`	number	yes	≥ 0
`lateral.soil.layers[].model = "liquefied-sand"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].units`	"SI" \| "US"	yes
`lateral.soil.layers[].model = "silt-cphi"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].model = "piedmont-residual"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].esi`	number	yes	> 0
`lateral.soil.layers[].esiBottom`	number	no	> 0
`lateral.soil.layers[].lambda`	number	no	> 0
`lateral.soil.layers[].model = "iso-clay"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].su`	number	yes	> 0
`lateral.soil.layers[].suBottom`	number	no	> 0
`lateral.soil.layers[].alpha`	number	no	0 – 1
`lateral.soil.layers[].gap`	"open" \| "closed"	no
`lateral.soil.layers[].clayType`	"soft" \| "stiff"	no
`lateral.soil.cycles`	number	no	integer, > 0
`axial`	object	yes
`axial.method`	"navfac-dm7-reese-oneill"	yes
`axial.pile`	object	yes
`axial.pile.kind = "uniform"`	variant	no
`axial.pile.length`	number	yes	> 0
`axial.pile.diameter`	number	yes	> 0
`axial.pile.tipArea`	number	no	> 0
`axial.pile.batterDeg`	number	no	0 – 45
`axial.pile.elasticModulus`	number	yes	> 0
`axial.pile.unitWeight`	number	yes	≥ 0
`axial.pile.displacement`	boolean	no
`axial.pile.deltaDeg`	number	no	0 – 60
`axial.pile.frictionFactor`	number	no	> 0
`axial.pile.kind = "sectioned"`	variant	yes
`axial.pile.sections[]`	object[]	yes	min 1 item
`axial.pile.sections[].top`	number	yes	≥ 0
`axial.pile.sections[].bottom`	number	yes	> 0
`axial.pile.sections[].diameter`	number	yes	> 0
`axial.pile.sections[].perimeter`	number	no	> 0
`axial.pile.sections[].area`	number	no	> 0
`axial.pile.tipArea`	number	no	> 0
`axial.pile.batterDeg`	number	no	0 – 45
`axial.pile.elasticModulus`	number	yes	> 0
`axial.pile.unitWeight`	number	yes	≥ 0
`axial.pile.displacement`	boolean	no
`axial.pile.deltaDeg`	number	no	0 – 60
`axial.pile.frictionFactor`	number	no	> 0
`axial.soil`	object	yes
`axial.soil.layers[]`	object[]	yes	min 1 item
`axial.soil.layers[].top`	number	yes	≥ 0
`axial.soil.layers[].bottom`	number	yes	> 0
`axial.soil.layers[].gamma`	number	yes	> 0
`axial.soil.layers[].type`	"cohesive" \| "cohesionless" \| "rock"	yes
`axial.soil.layers[].cohesion`	number	no	≥ 0
`axial.soil.layers[].phi`	number	no	0 – 60
`axial.soil.layers[].sptN`	number	no	≥ 0
`axial.soil.layers[].qu`	number	no	≥ 0
`axial.soil.layers[].rockJointCondition`	"massive-intact" \| "closed" \| "open-or-gouge-filled"	no
`axial.soil.layers[].rqd`	number	no	0 – 100
`axial.soil.layers[].kDown`	number	no	> 0
`axial.soil.layers[].kUp`	number	no	> 0
`axial.soil.layers[].kc`	number	no	> 0
`axial.soil.layers[].ka`	number	no	> 0
`axial.soil.waterTableDepth`	number	no	≥ 0
`axial.soil.waterUnitWeight`	number	no	> 0
`axial.capacity`	object	yes
`axial.capacity.segments`	number	yes	integer, 20 – 500
`axial.capacity.penetrationRatioSide`	number	yes	> 0
`axial.capacity.penetrationRatioTip`	number	yes	> 0
`axial.capacity.kDown`	number	yes	> 0
`axial.capacity.kUp`	number	yes	> 0
`row`	object	yes
`row.pileCount`	number	yes	integer, > 0
`row.spacing`	number	yes	> 0
`row.tributaryWidth`	number	yes	> 0
`row.orientation`	"normal-to-movement"	yes
`row.interactionMethod`	"independent-wide-spacing"	yes
`surfaces[]`	object[]	yes	min 1 item, max 60 items
`surfaces[].id`	string	yes
`surfaces[].slidingDepth`	number	yes	> 0
`surfaces[].distributedDemand`	number	yes	> 0
`soilDisplacement`	number	yes	> 0
`slipAngleDeg`	number	yes	0 – 90
`maxDisplacementCap`	number	yes	> 0
`increments`	number	yes	integer, 20 – 800
`axialSegments`	number	yes	integer, 20 – 800
`convergenceTolerance`	number	yes	0 – 0.01
`lateralRelaxation`	number	yes	0 – 1
`axialRelaxation`	number	yes	0 – 1
`maxIterations`	number	yes	integer, 2 – 5000
`layering`	"direct" \| "georgiadis"	yes

Response fields

Field	Type	Description
`method`	object	Exact released method, edition, interaction selector, and minimum spacing in pile diameters.
`row`	object	Echoed row definition plus the computed minimum independent spacing in request length units.
`points[]`	object[]	One successful lateral-plus-axial solve per candidate surface, in declared depth order.
`points[].surfaceId`	string	Stable candidate-surface identifier from the request.
`points[].slidingDepth`	number	Depth where the candidate surface crosses the pile, in the declared unit system.
`points[].lateralResistance`	number	Single-pile p-y shear at the candidate surface.
`points[].axialResistance`	number	Single-pile t-z internal axial force at the candidate surface.
`points[].resultant`	number	Vector magnitude of component resistance, reported as a diagnostic only.
`points[].tangentResistance`	number	Work-conjugate single-pile resistance tangent to slip movement; used for capacity.
`points[].rowCapacity`	number	Pile count × interaction factor × tangent resistance.
`points[].totalDemand`	number	Distributed driving demand × declared tributary width.
`points[].demandCapacityRatio`	number	Total candidate demand divided by row capacity.
`points[].capacityMargin`	number	Row capacity minus total demand.
`points[].lateralIterations`	integer	Nonlinear iterations used by the p-y solve.
`points[].axialIterations`	integer	Nonlinear iterations used by the t-z solve.
`governingSurface`	object	Candidate with the largest demand/capacity ratio, not the largest resistance.
`convergence`	object	Successful all-surface convergence stamp and maximum component iteration counts.

Code examples

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

POST /v1/slope

curl https://api.pilecalc.com/v1/slope \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "applied-displacement-independent-wide-spacing",
  "lateral": {
    "pile": {
      "kind": "uniform",
      "length": 12,
      "diameter": 0.61,
      "ei": 143000,
      "groundSurfaceDepth": 0
    },
    "soil": {
      "layers": [
        {
          "model": "soft-clay",
          "top": 0,
          "bottom": 5,
          "gamma": 8.5,
          "c": 28,
          "e50": 0.02
        },
        {
          "model": "sand-reese",
          "top": 5,
          "bottom": 12,
          "gamma": 9.5,
          "phi": 34,
          "k": 16300
        }
      ]
    }
  },
  "axial": {
    "method": "navfac-dm7-reese-oneill",
    "pile": {
      "kind": "uniform",
      "length": 12,
      "diameter": 0.61,
      "elasticModulus": 200000000,
      "unitWeight": 77,
      "displacement": true
    },
    "soil": {
      "layers": [
        {
          "top": 0,
          "bottom": 5,
          "gamma": 18,
          "type": "cohesive",
          "cohesion": 28
        },
        {
          "top": 5,
          "bottom": 12,
          "gamma": 19,
          "type": "cohesionless",
          "phi": 34
        }
      ]
    },
    "capacity": {
      "segments": 120,
      "penetrationRatioSide": 20,
      "penetrationRatioTip": 20,
      "kDown": 1,
      "kUp": 1
    }
  },
  "row": {
    "pileCount": 5,
    "spacing": 3.66,
    "tributaryWidth": 18.3,
    "orientation": "normal-to-movement",
    "interactionMethod": "independent-wide-spacing"
  },
  "surfaces": [
    {
      "id": "surface.01",
      "slidingDepth": 1,
      "distributedDemand": 45
    },
    {
      "id": "surface.02",
      "slidingDepth": 2,
      "distributedDemand": 55
    },
    {
      "id": "surface.03",
      "slidingDepth": 3,
      "distributedDemand": 65
    },
    {
      "id": "surface.04",
      "slidingDepth": 4,
      "distributedDemand": 75
    },
    {
      "id": "surface.05",
      "slidingDepth": 5,
      "distributedDemand": 85
    },
    {
      "id": "surface.06",
      "slidingDepth": 6,
      "distributedDemand": 95
    },
    {
      "id": "surface.07",
      "slidingDepth": 7,
      "distributedDemand": 105
    },
    {
      "id": "surface.08",
      "slidingDepth": 8,
      "distributedDemand": 115
    }
  ],
  "soilDisplacement": 0.05,
  "slipAngleDeg": 30,
  "maxDisplacementCap": 0.3,
  "layering": "direct",
  "increments": 120,
  "axialSegments": 120,
  "convergenceTolerance": 1e-7,
  "lateralRelaxation": 0.4,
  "axialRelaxation": 0.5,
  "maxIterations": 1000
}'

The GET variant returns governingSurface.demandCapacityRatio,points.0.rowCapacity 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

Use governingSurface.demandCapacityRatio for the supplied pile-row check. It is not the slope's global factor of safety.
points[].resultant is not the design capacity. The declared capacity uses the work-conjugate tangentResistance and the explicit row aggregation.
The API never returns a successful point with converged: false. Any failed lateral or axial solve produces an actionable engine error for the request.
Spacing below six maximum pile diameters, unsupported orientation/interaction, mismatched component geometry, cyclic input, buried coordinates, unordered surfaces, and incomplete soil coverage fail contract validation.

Close-spacing interaction is not modeled

independent-wide-spacing has interaction factor 1.0 only inside its declared envelope. Do not emulate shadowing by altering pile count or spacing; rows spaced closer than the declared envelope are rejected explicitly.