Skip to main content

Auto Top-Up

Agent-callable endpoint to autonomously top up credits. Requires auto_topup_enabled to be set by a human. Returns 403 if not enabled.

AI agents call this endpoint to autonomously add credits when the balance falls below the configured threshold. A human must first enable auto top-up via PATCH /v1/billing/settings.

This endpoint is idempotent when the balance is already above the threshold — it returns topped_up: false without adding credits. Agents can safely call it on every extraction cycle without risk of over-provisioning.

Combine this endpoint with the X-Talonic-Balance-Credits response header from POST /v1/extract to build an autonomous credit management loop. Check the balance header after each extraction and call top-up when it drops below your threshold.
POST/v1/billing/topup

Response

Response fields (topped up)

topped_upbooleantrue if credits were added.
amount_creditsintegerNumber of credits added.
new_balance_creditsintegerNew credit balance after the top-up.
new_balance_eurnumberNew balance converted to EUR at the configured rate.

Response fields (not needed)

topped_upbooleanfalse when balance was already above the threshold.
reasonstringAlways `balance_above_threshold` when topped_up is false.
balance_creditsintegerCurrent credit balance.
balance_eurnumberCurrent balance converted to EUR.
threshold_creditsintegerConfigured top-up threshold.

Response (topped up)

{
  "topped_up": true,
  "amount_credits": 50000,
  "new_balance_credits": 54930,
  "new_balance_eur": 54.93
}

Response (not needed)

{
  "topped_up": false,
  "reason": "balance_above_threshold",
  "balance_credits": 64930,
  "balance_eur": 64.93,
  "threshold_credits": 5000
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
403auto_topup_disabledAuto top-up is not enabled. A human must enable it via PATCH /v1/billing/settings.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Billing Settings
Credits Balance