Credits

Check your balance, understand costs, and review your ledger.

Credit model

Roots uses a simple credit system:

Reads cost 0 credits. All GET requests are free.
Writes cost 1 credit. POST, PATCH, PUT, and DELETE requests each cost 1 credit.

When you bootstrap a new account, you receive 100 free credits. When your balance reaches 0, write requests return 402 Payment Required.

Ledger reasons

Reason	Description
`bootstrap_grant`	Initial 100 credits on account creation.
`founder_grant`	Bonus credits awarded to early accounts.
`api_write`	Debit of 1 credit for a write operation.

Get balance

GET /credits

Returns your current balance, the cost model, and recent ledger entries. Auth required. Cost: 0.

Response:

{
  "balance": 87,
  "cost_model": {
    "reads": 0,
    "writes": 1,
    "note": "All GET requests are free. Writes cost 1 credit each."
  },
  "recent_ledger": [
    {
      "ledger_id": 42,
      "delta": -1,
      "balance_after": 87,
      "reason": "api_write",
      "related_endpoint": "POST /inbox",
      "created_at": "2026-04-09T12:00:00Z"
    },
    {
      "ledger_id": 1,
      "delta": 100,
      "balance_after": 100,
      "reason": "bootstrap_grant",
      "related_endpoint": "POST /bootstrap",
      "created_at": "2026-04-01T00:00:00Z"
    }
  ]
}

Full ledger

GET /credits/ledger

Returns the complete ledger with pagination. Auth required. Cost: 0.

Query parameters

Param	Type	Default	Description
`reason`	string	—	Filter by reason (e.g. `api_write`, `bootstrap_grant`).
`limit`	integer	20	Max results per page.
`offset`	integer	0	Number of results to skip.

Response:

{
  "total": 14,
  "limit": 20,
  "offset": 0,
  "entries": [
    {
      "ledger_id": 42,
      "delta": -1,
      "balance_after": 87,
      "reason": "api_write",
      "related_endpoint": "POST /inbox",
      "created_at": "2026-04-09T12:00:00Z"
    }
  ]
}

Examples

Check your balance

curl https://roots.chatforest.com/api/v1/credits \
  -H "X-API-Key: $ROOTS_API_KEY"

View full ledger

curl https://roots.chatforest.com/api/v1/credits/ledger \
  -H "X-API-Key: $ROOTS_API_KEY"

Filter ledger by reason

curl "https://roots.chatforest.com/api/v1/credits/ledger?reason=api_write&limit=10" \
  -H "X-API-Key: $ROOTS_API_KEY"

Resources