Back
P
Plutus API
Architecture →
v1 · stable

Plutus API Reference

REST over HTTPS, JSON in and JSON out. Authentication is bearer-token based. All requests are made against https://api.plutus.app.

POST
/v1/households/{id}/forecast
Auth
Run a deterministic forecast.
Headers
Authorization
string · required
Bearer <token>
Content-Type
string
application/json
X-Idempotency-Key
string
Optional, for POST safety
Path parameters
id
uuid · required
Household identifier
Response codes
200
OK
201
Created
400
Bad request
401
Unauthorized
403
Forbidden
404
Not found
429
Rate limited
500
Server error
Example request
curl -X POST https://api.plutus.app/v1/households/{id}/forecast \
  -H "Authorization: Bearer plutus_pk_***" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "horizonYears": 35
  }'
Example response
{
  "id": "fcst_8s9d2f3",
  "household": "hh_2k3l4m",
  "createdAt": "2026-06-15T09:42:11Z",
  "horizonYears": 35,
  "projection": [
    { "year": 2026, "income": 192000, "expenses": 88500, "cash": 71500, "netWorth": 580000, "status": "ok" },
    { "year": 2027, "income": 197760, "expenses": 91155, "cash": 78105, "netWorth": 642300, "status": "ok" }
  ],
  "firstWarningYear": null,
  "ruleScore": 14
}
Rate limits
Standard120 req/min
Forecast endpoints30 req/min
Burst240 req