API Reference

Base URL: https://api.spendaqo.com/v1

POST /v1/classify

Classifies a batch of transactions and returns corrected category labels, confidence scores, and a cash-flow forecast signal.

Request body

Field	Type	Required	Description
`account_id`	string	yes	Your internal account identifier
`transactions[]`	array	yes	Array of transaction objects (max 500)
`transactions[].id`	string	yes	Your transaction ID (returned in response)
`transactions[].amount_cents`	integer	yes	Transaction amount in cents
`transactions[].merchant_name`	string	yes	Raw merchant name string from bank
`transactions[].raw_category`	string	optional	Original category label from data source
`transactions[].date`	string	optional	ISO 8601 date (required for forecast)

GET /v1/forecast/{account_id}

Returns the current 90-day rolling cash-flow forecast signal for an account, based on its corrected transaction history.

Query parameters

Parameter	Type	Description
`horizon`	integer	Forecast horizon in days (default: 90, max: 90)
`as_of`	string	ISO 8601 date for point-in-time forecast (optional)

Error codes

Code	Meaning
`400`	Bad request — malformed JSON or missing required fields
`401`	Unauthorized — invalid or missing API key
`429`	Rate limited — requests per minute or monthly limit exceeded
`500`	Internal server error — safe to retry with exponential backoff

Request example

POST /v1/classify
Authorization: Bearer spq_live_...
Content-Type: application/json

{
  "account_id": "acct_kst_8841",
  "transactions": [{
    "id": "txn_001",
    "amount_cents": 8499,
    "date": "2026-06-10",
    "merchant_name": "AMZN*MKTP",
    "raw_category": "DEBIT_MISC"
  }]
}

200 OK response

{
  "status": 200,
  "latency_ms": 142,
  "results": [{
    "id": "txn_001",
    "corrected_category":
      "Office Supplies",
    "confidence_score":
      0.97,
    "original_category":
      "DEBIT_MISC"
  }],
  "forecast_signal":
    "stable_positive",
  "forecast_confidence":
    0.83
}