Skip to main content

Auto Top-Up

Let AI agents autonomously replenish API credits with POST /v1/billing/topup. Requires human pre-authorization via billing settings and the billing scope.

The auto top-up endpoint (POST /v1/billing/topup) lets an AI agent autonomously add credits to a Talonic account when the balance falls below the configured threshold. It adds the preconfigured auto_topup_amount in one call, with no request body. A human must first enable auto top-up via PATCH /v1/billing/settings; until then the endpoint returns 403.

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
The billing scope must be explicitly granted to the API key. Existing keys do not have it by default.

cURL — Trigger an auto top-up

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
Cost Response Headers