HTTP API reference
Every analysis in the app is a thin layer over a clean HTTP API. Run the engine from your own scripts, CI, or spreadsheets.
Every analysis in the app is a thin layer over a clean HTTP API. The web app never computes anything itself — it sends your inputs to the same engine you can call directly from your own scripts, CI pipelines, or spreadsheets. The request and response shapes are defined by a shared schema, so what you see in the app is exactly what the API accepts.
The API is served at https://api.pilecalc.com. Analysis endpoints take a JSON POST body and return JSON; each also has a GET variant for callers that cannot send headers.
Prefer an AI or agent client? The same analysis catalog is available through the PileCalc MCP server and ChatGPT integration.
Authentication
Requests are authenticated with an API key. Create one from your Settings → API keys, then send it as a bearer token on every request:
Authorization: Bearer <your_api_key>On the GET variant only, the key may ride in the URL instead — ?key=<your_api_key> — for tools like Excel that cannot set headers. Prefer the header everywhere else: URLs end up in access logs.
Each key is tied to your account and your subscription plan, which together determine your rate limits. Treat keys like passwords — they grant full access to run analyses under your account. You can revoke a key at any time from the same screen.
Keep keys server-side
Endpoints
One endpoint per analysis type, each with its own reference page — generated request-field tables, response fields, and runnable curl / JavaScript / Python examples:
| Endpoint | Reference | Computes |
|---|---|---|
POST /v1/lateral | Lateral (p-y) | Laterally loaded pile — COM624P finite difference |
POST /v1/axial | Axial | Axial capacity & settlement — NAVFAC DM-7.02, t-z/Vesić |
POST /v1/footing | Footing | Shallow footing — bearing, settlement, sliding, tilt |
POST /v1/drilled-shaft | Drilled shaft | Bored-pile capacity — FHWA-IF-99-025 |
POST /v1/group-vertical | Group · vertical | Group capacity, efficiency & settlement |
POST /v1/group-lateral | Group · lateral | Row-by-row p-multiplier group analysis |
POST /v1/uplift | Uplift | Plate/helix breakout & anchor bond capacity |
POST /v1/moment-curvature | Moment–curvature | Fiber-integrated M–φ & nonlinear EI |
POST /v1/slope | Slope | Pile-row demand/capacity across candidate slip surfaces |
Two helper endpoints round out the surface:
GET /v1/usage— your current plan, quota, and remaining calls (key required, not metered).GET /v1/health— service status (no key required).
The GET variant & fields
Every analysis endpoint also answers GET, for header-less callers like Excel's WEBSERVICE() and Sheets' IMPORTDATA():
GET /v1/<type>?key=<api_key>&req=<url-encoded JSON>&fields=<dot.paths>req is the exact POST body, URL-encoded and validated by the same schema. Without fields you get the full JSON response; with it, a text/plain CSV of the selected scalar leaves (e.g. fields=head.deflection,maxMoment.value — numeric segments index arrays), which drops straight into a spreadsheet cell. Auth, plan gating, and metering are identical to POST. The Excel integration guide covers this end to end.
Rate limits & quotas
API access is included on the Pro and Business plans (the Free plan has none). Each paid plan includes a monthly allowance of API calls (resetting on the 1st, UTC) plus a per-minute burst guard. Successful analysis calls count against your quota; rejected requests (auth or validation failures) do not, and neither do /v1/usage and /v1/health.
| Plan | Calls / month | Burst / minute |
|---|---|---|
| Free | — | — |
| Pro | 1,000 | 30 |
| Business | 5,000 | 60 |
Successful responses include X-RateLimit-Limit (your monthly quota) and X-RateLimit-Remaining (calls left this month) headers. Call GET /v1/usage any time for a snapshot of where you stand.
Errors
Every error has the shape { "error": { "code", "message", issues? } }. The full list:
validation_error— the request failed schema validation — the body, the GET req/fields params, or a bad JSON payload (see issues).unauthorized— missing, invalid, or revoked API key.engine_error— inputs were valid but the analysis could not complete (e.g. a physically impossible profile).rate_limited— per-minute burst exceeded — retry after the Retry-After header (seconds).quota_exceeded— monthly quota reached — upgrade or wait for the reset on the 1st (UTC).Validation errors list each problem keyed by its field path — the same validation that powers the app's inline errors:
{ "error": { "code": "validation_error",
"issues": [ { "path": ["pile","diameter"], "message": "Number must be greater than 0" } ] } }Units
The API is unit-agnostic: supply any self-consistent system and results come back in the same units. There are no hidden conversions, so the rules in Units & sign conventions apply equally to API calls — in particular the water unit weight for axial and shaft analyses. The examples on the per-endpoint pages all use SI (m, kN, kPa, kN/m³).